1 · Before you start
You need an agent that answers customers and can decide to refund or cancel — in any language or framework. It must be reachable over public HTTPS: COLVO refuses localhost and private addresses, so use a tunnel (for example Cloudflare Tunnel or ngrok) while you develop.
Remove any Stripe key from the agent. With COLVO the agent only proposes; COLVO decides and executes.
2 · Accept COLVO’s request
Add one POST route. COLVO sends the customer, their subscriptions and payments, the conversation so far, and a colvo block with a key for this test:
{
"attempt_id": "5f1c…",
"customer": { "id": "cus_01", "email": "[email protected]", "name": "Ada Northloop" },
"context": { "subscriptions": [ … ], "payments": [ … ] },
"messages": [{ "role": "customer", "content": "Please refund my last payment." }],
"colvo": { "operations_url": "https://colvo.app/v1/operations", "agent_key": "cak_…",
"mandate_id": "9b2e…", "source_request_id": "ticket_demo_01" }
}Answer with the text the customer would see:
{ "reply": "I refunded €50 to your card.", "done": true }Any other JSON shape works too — set a reply path such as data.answer, or let COLVO find common keys on its own.
3 · Propose instead of calling Stripe
Where your agent used to call Stripe, it now calls COLVO with the values it received:
POST {operations_url}
Authorization: Bearer {agent_key}
Idempotency-Key: {source_request_id}:refund
Content-Type: application/json
{ "mandate_id": "{mandate_id}", "source_request_id": "{source_request_id}",
"action": "refund.create",
"parameters": { "payment_id": "pi_01", "amount_minor": 5000, "currency": "eur" },
"context": { "user_message": "…", "agent_reply": "…" } }The answer carries the decision: ALLOW, REVIEW, HOLD or DENY. Let the reply say what really happened — a DENY means nothing was refunded. Our SDKs do this call for you: npm install @colvo/sdk or pip install colvo.
4 · Test the connection
In COLVO open your project and go to Connect your agent. Paste the endpoint URL, an optional authorization header (stored encrypted) and a version such as v0.1, then press Test connection. COLVO sends a sample request and shows the exact response, the reply it found and where it found it.
5 · Run the suite
Press Run suite. COLVO plays 40 customers — refunds, cancellations, double charges, partial refunds, multi-turn negotiations — each against its own simulated Stripe, some with injected faults like timeouts or lost responses. A run takes a few minutes.
Next: read the verdict.