Refund endpoint (Actions API)

purser never touches money and stores no payment credentials. To refund, it calls an endpoint of your own, and your system does the refund. This page is the technical specification of that endpoint; when the AI offers a refund, who approves it, limits and freezing are covered in Refunds.

purser sends your endpoint three kinds of request:

The refund amount always comes from your refund.preview, never from the model.

Turning it on in the consoleCopy Anchor Link

Settings (设置) → Refunds (退款), owners and admins:

1. Refund endpoint URL (退款接口地址): an address on your server; it must be https://;
2. Create secret (生成密钥): the signing secret is shown once; copy it into your server's environment (for example PURSER_ACTIONS_SECRET). Afterwards only its last 4 characters are shown;
3. Test connection (测试连接): purser sends a signed ping and shows the result on the page;
4. How to refund (怎么退): Refund directly (直接退款, your endpoint refunds when it receives the request) or Only submit a refund request (只提交退款申请, your endpoint records it and reports the outcome later);
5. Switch on Enabled (启用).

To change the secret, click New secret (换新密钥): the new one is also shown once, and the old one stops working immediately, so update your server at the same time.

Refund actions need the Growth or Scale plan (test workspaces can use them right away); see Plan and billing.

Request formatCopy Anchor Link

POST <your endpoint URL>
content-type: application/json
user-agent: purser-actions/1
purser-signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
purser-idempotency-key: <idempotency key>

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

For ping, data is an empty object {}.

When an agent checks the amount in the inbox before confirming, refund.preview can be sent before the refund exists; data.actionId is then an empty string.

What to answerCopy Anchor Link

Always JSON, status 200:

• amount must be a non-negative integer (minor units) and currency a three-letter code in capitals. Anything else counts as "no answer".
• The status of refund.create must be succeeded or pending. pending means you accepted it and will report the outcome later (in Only submit a refund request mode, answer pending).
• In a refusal, code is your own machine-readable reason and message is recorded for your agents. A refusal is final and is not retried.

Checking the signatureCopy Anchor Link

purser-signature looks like t=<unix seconds>,v1=<hex signature>. The signature is HMAC-SHA256 with the signing secret over the string "<t>.<raw body>":

• the key is the whole string the console gave you (it starts with whsec_, and the prefix is part of it);
• compute it over the raw body you received; do not parse the JSON and serialise it again;
• refuse it if t is more than 5 minutes (300 seconds) away from your server's clock;
• compare in constant time.

If the signature does not check out, answer 401 with { "ok": false, "code": "bad_signature" }. purser records the refund as failed and does not retry.

A Node.js (Express) example without the SDK:

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();

// Take the raw body with text(); parse it only after the signature is checked
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") {
      // Refund at most once per idempotency key
      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 retries later with the same idempotency key
    return res.status(500).json({ ok: false, code: "error" });
  }
});

Replace db and refundOrder with your own code.

Idempotency and retriesCopy Anchor Link

• The idempotency key of refund.create is the refund's actionId, and it is the same on every retry (id changes each time). Refund at most once per idempotency key, and answer with the first result when you see a key again. Then a retry from purser can never refund a customer twice.
• purser waits at most 10 seconds per request and does not follow redirects.
• A timeout, a failed connection, a non-2xx response that is not a { "ok": false, … } refusal like the ones above, or a 2xx that is not a valid JSON answer (or has an unknown status): all count as "no answer".
• With no answer, refund.create is retried with backoff, up to 5 retries (the first after 20 seconds, then growing exponentially). If every attempt fails, the refund is recorded as failed and your agents see why on the Refunds (退款) page.
• ping and refund.preview are not retried: no answer means that attempt failed (Test connection shows a failure; the AI does not offer that refund; the agent sees an error).

Reporting the outcomeCopy Anchor Link

If refund.create answered pending (including in Only submit a refund request mode), call this with your API secret key (sk_…, see REST API and Node SDK) once the refund is done:

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" }'

The answer is { "id": "…", "status": "…" }, or 404 if the refund is not in this workspace. Only a refund still waiting for its outcome (pending, or still being sent) is updated; a finished one stays as it is and its current status is returned. The customer is told the outcome in the original conversation.

Refund statusesCopy Anchor Link

The statuses you see on the Refunds (退款) page and in the list_refunds tool of MCP:

With the SDK (once published)Copy Anchor Link

actionsHandler in @purser-ai/node checks the signature, dispatches by type and answers in the right JSON; if your function throws, it answers 500 and purser retries. The package is not published on npm yet; until it is, use the code above.

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

const handle = actionsHandler({
  secret: process.env.PURSER_ACTIONS_SECRET,
  refund: {
    // Calculate only, move no money. Amounts in minor units.
    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 };
    },
    // The real refund. Refund at most once per 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 };
    },
  },
});

// Fetch-style servers such as Cloudflare Workers, Bun, Deno, Hono:
export default { fetch: (request) => handle(request) };

verifyActionSignature(secret, body, header) is also exported, if you only want the signature check.

SafetyCopy Anchor Link

• The amount always comes from your refund.preview; the amount in refund.create is exactly the number the customer confirmed;
• the AI only offers refunds for a signed-in customer's own orders, within the periods your return policy allows; one refund per order at a time, and an order already refunded through purser is not offered again;
• in the console's Try it (试聊), the customer can click confirm, but refund.create is never called.