Install the SDK, open an operation against stripe.refund.succeeded, make the refund call with the idempotency key from begin, submit the response, and call verify. The first verified outcome takes under ten minutes with an Official skill.

Which steps does the quick start take?

Verify a Stripe refund with the TypeScript SDK

  1. Install the SDK.Run npm install @provely/sdk or pip install provely.
  2. Set the API key.Create a key in the dashboard and export it as PROVELY_API_KEY. The SDK reads it. The key never goes to the agent prompt.
  3. Connect Stripe with a read-only key.Call POST /v1/connections with a restricted Stripe key that can read refunds. The verifier reads with this key. Your agent keeps its own write key.
  4. Begin the operation.Call begin with the contract stripe.refund.succeeded and the input { charge_id, amount_cents }. Keep op.idempotency_key.
  5. Make the refund call.Call stripe.refunds.create with the Idempotency-Key header set to op.idempotency_key.
  6. Submit the acknowledgement.Call op.actionResult(refund) with the Stripe response.
  7. Verify and report.Call op.verify(). Report the verdict exactly as returned. On VERIFIED, download the receipt with op.receipt().
The whole loop
import { Provely } from '@provely/sdk';
import Stripe from 'stripe';

const provely = new Provely({ baseUrl: 'https://api.provely.sh' });
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

const op = await provely.begin({
  contract: 'stripe.refund.succeeded',
  input: { charge_id: 'ch_3QxT5s2eZvKYlo2C', amount_cents: 14200 },
});

const refund = await stripe.refunds.create(
  { charge: 'ch_3QxT5s2eZvKYlo2C', amount: 14200 },
  { idempotencyKey: op.idempotency_key },
);

await op.actionResult(refund);
const verification = await op.verify();

switch (verification.verdict) {
  case 'VERIFIED':
    console.log('The action is verified complete. Receipt:', verification.receipt_id);
    break;
  case 'PENDING':
    console.log('The action is accepted but not yet verified. Operation:', op.id);
    break;
  default:
    console.log('Verification did not confirm the outcome:', verification.verdict, verification.reason);
}
The same loop in Python
from provely import Provely

provely = Provely(base_url="https://api.provely.sh")
op = provely.begin(
    contract="stripe.refund.succeeded",
    input={"charge_id": "ch_3QxT5s2eZvKYlo2C", "amount_cents": 14200},
)
refund = stripe.Refund.create(
    charge="ch_3QxT5s2eZvKYlo2C", amount=14200, idempotency_key=op.idempotency_key
)
op.action_result(refund)
verification = op.verify()
print(verification.verdict)  # VERIFIED, PENDING, CONTRADICTED, FAILED, or UNVERIFIABLE

What does each verdict mean for the agent?

VerdictWhat the agent says
VERIFIED"The action is verified complete. Receipt: <id>."
PENDING"The action is accepted but not yet verified. Operation: <id>."
CONTRADICTED"Verification found a different outcome than requested. Do not retry blindly."
UNVERIFIABLE"I cannot prove the outcome. Treat the action as unconfirmed."
FAILED"The provider reports that the action failed."

Can I skip begin and only call verify?

No. begin binds the idempotency key and the correlation keys to the operation. Without it the runtime cannot tell your refund from a pre-existing one, and a pre-existing match must not verify.

How long does verify wait?

One call observes once and returns. PENDING is a normal answer. Call status later, or use provely verify --wait 10m from the CLI to poll until a terminal verdict.