Countersign

API & MCP

One endpoint to ask, one to check. Every decision comes back with a message your agent can say to the customer as is.

Request a refund

POST https://countersign.vibiz.app/api/v1/refunds/request with Authorization: Bearer cs_….

charge_idStripe charge (ch_…). Or payment_intent_id (pi_…).
amountInteger, smallest currency unit: 2400 = $24.00. Required.
reasonShort reason, as the customer gave it.
agent_reasoningWhy the agent thinks it is fair. Shown to the approver.
ticket_urlLink to the conversation. Shown to the approver.
customer_emailWho the agent believes this is. Logged; the real customer comes from Stripe.
callback_urlWe POST the final decision here, signed (Countersign-Signature).
request_idIdempotency: the same id returns the same request. Also the Idempotency-Key header.
stripe_accountWith several Stripe accounts connected: which one (acct_…).
response
{
  "id": "rr_…",
  "status": "approved_and_refunded" | "pending" | "denied" | "expired" | "approved_refund_failed",
  "message": "Refund of $24.00 was issued (re_…). Tell the customer…",
  "approval": "policy" | "person" | null,
  "denied_rule": "refundable_balance" | null,
  "rule_trace": [{ "rule": "auto_cap", "label": "Auto-approve up to $50.00", "outcome": "pass", "detail": "…" }],
  "stripe_refund_id": "re_…",
  "status_url": "https://countersign.vibiz.app/api/v1/refunds/rr_…",
  "expires_at": "…"
}

Check a request

GET https://countersign.vibiz.app/api/v1/refunds/:id, same key, same response shape.

MCP server

Streamable HTTP at https://countersign.vibiz.app/api/mcp. Tools: request_refund, get_refund_status.

shell
claude mcp add --transport http countersign https://countersign.vibiz.app/api/mcp --header "Authorization: Bearer cs_YOUR_KEY"

Callbacks

When a pending request is decided, expires or fails, we POST { type: "refund_request.updated", data: <the request> } to your callback_url (and webhook endpoints on Team and Scale). Verify Countersign-Signature: t=…,v1=…: HMAC-SHA256 of `${t}.${body}` with your signing secret from Dashboard → Integrations.

Errors

Every error is { error: { code, message, fix } }: what failed, why, and how to fix it.

Guarantees