Guides / Refunds

Refunds

Programmatic refund flow honoring ToS §3.4. Request within 30 days, auto-resolved within 24h.

The flow

1. Agent requests: POST /v1/refunds with the original transaction_id
2. Provider has 24h to respond — approve or deny
3. If no response in 24h, auto-approval via cron job (5-min poll)
4. Approval triggers atomic refund: 90% returns to agent wallet, Provider's pending revenue debited, Hub keeps 10% as processing cost
5. Webhook events fire: refund.requested, invocation.refunded or refund.denied

Request a refund

import { JecpClient, InsufficientBudgetError } from '@jecpdev/sdk';

const r = await jecp.requestRefund({
  transaction_id: 'tx-abc-123',
  reason: 'Provider returned wrong language (asked JA, got KO)',
  evidence_url: 'https://i.imgur.com/screenshot.png',  // optional
});

console.log(r.refund_id);            // 'rf-...'
console.log(r.status);               // 'requested'
console.log(r.estimated_resolution); // '2026-05-10T15:00:00Z'

Validation rules

From the CLI

jecp refund request tx-abc-123 --reason "wrong language"
jecp refund list
jecp refund get rf-xxx

Provider side: approve / deny

Providers receive a refund.requested webhook event when a refund is requested. They have 24 hours to respond:

curl -X POST https://jecp.dev/v1/refunds/rf-xxx/approve \
  -H "Authorization: Bearer jdb_pk_..."

# or
curl -X POST https://jecp.dev/v1/refunds/rf-xxx/deny \
  -H "Authorization: Bearer jdb_pk_..." \
  -d '{"reason":"output was correct, agent provided ambiguous input"}'

The economics

Original $0.005 charge:

• Provider received: $0.00425 (85%)
• Hub fee: $0.0005 (10%)
• Payment processing: $0.00025 (5%)

On refund:

• Agent gets back: $0.0045 (90%)
• Provider loses: $0.00425 (debited from pending balance)
• Hub keeps: $0.0005 (processing cost)
• Payment processing: not recoverable from Stripe

Webhook integration

Both agents and providers can subscribe to refund-related events. See the webhooks guide.