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_…).{
"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.
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.
missing_api_key / invalid_api_key / api_key_revoked (401)Send Authorization: Bearer cs_… from Dashboard → Integrations.
missing_charge / missing_amount / invalid_amount / invalid_url (400)Fix the field named in error.param; amount is an integer in cents.
charge_not_found (404)The charge or payment intent is not in the connected Stripe account or mode.
stripe_not_connected / mode_mismatch (409)Connect Stripe, or use a key of the same mode (test vs live) as the charge.
stripe_permission_missing / stripe_key_invalid (502)The connected restricted key lost a permission or was rolled; reconnect it.
quota_exceeded (402)The plan quota for this month is used. Upgrade or wait for the 1st (UTC).
Guarantees
- The rules run on the charge as Stripe reports it, not on what the agent says.
- The first answer wins; later taps see the decision that stood.
- The refund is created with the idempotency key
cs_<request id>after a fresh read of the refundable balance. - The audit log is append-only at the database level.