Stripe adapter
Decide with the policy, reserve against the caps, send once with an idempotency key, read the Stripe record back and sign the outcome. Test mode, standard library only.
On this page
verdock.adapters.stripe.StripeAdapter handles payouts and one more money operation in Stripe test mode. It uses only the Python standard library. The offline commands (verdock init, check, verify, demo) still make no network calls. The adapter calls the Stripe API only when you use it.
Configure keys#
Keys come from your environment or the constructor.
| Provider | Environment variable |
|---|---|
| Stripe | STRIPE_API_KEY |
verdock.adapters.load_env(".env") reads one file, sets only those names, never replaces a variable that is already set, never prints a value and returns the names it set. Keys are never written to receipts, state files or logs, are redacted from error messages and are sent only to the Stripe API host.
Send a payout#
from verdock.adapters import load_env
from verdock.adapters.stripe import StripeAdapter
load_env(".env")
stripe = StripeAdapter() # policy: verdock.yaml, state: .verdock
result = stripe.payout(amount_minor=2500, currency="USD", counterparty="cus_123",
request_key="order-77-payout")
print(result.state) # VERIFIED, PENDING, MISMATCH or UNKNOWNimport { StripeAdapter, loadEnv } from 'verdock';
loadEnv('.env');
const stripe = new StripeAdapter();
const result = await stripe.payout({
amountMinor: 2500, currency: 'USD', counterparty: 'cus_123',
requestKey: 'order-77-payout',
});
console.log(result.state);Amounts are positive integers in minor units. Floats, booleans, zero, negatives, a currency that is not three upper case letters and malformed ids are refused before anything else happens. request_key must be unique per adapter state folder. The policy needs an entry for the operation and both daily caps, team_per_day_minor and per_customer_per_day_minor. See the policy file.
What every call does#
- Decides with the policy before any network call. A blocked or approval required action writes an
adapter.blockedreceipt and raisesRefused. No request is sent. - Derives a stable request id from the operation, the counterparty and the request key. Reserves the amount against the team and counterparty caps. A cap refusal also happens before any request.
- Records the expectation in the outcome log and writes an
adapter.admittedreceipt. - Sends the request once, with the request id as the Stripe
Idempotency-Key. - Reads the Stripe record back with a separate GET and compares amount, currency, status and request id with the expectation. The result is VERIFIED, MISMATCH, UNKNOWN or PENDING. An
adapter.outcomereceipt is written.
A reservation is committed on VERIFIED. It stays held on UNKNOWN, PENDING and MISMATCH. If Stripe rejects the request with a 4xx answer, the reservation is released, the state is REJECTED and a ProviderError is raised. Calling again with a request_key that was already used never sends a second request. A request that matches returns the recorded outcome with replayed=True. A request that differs raises Refused.
Request id and read back#
| Stripe payout | |
|---|---|
| Create | POST /v1/payouts |
| Idempotency | Idempotency-Key header |
| Request id in the record | metadata[verdock_request_id] |
| Read back | GET /v1/payouts/{id} |
| Find without the id | List payouts, match metadata |
Lost responses#
A connection error, a timeout, a 5xx answer, or a response that cannot be parsed means Stripe has or has not acted. The state is UNKNOWN. The adapter does not retry. The reservation is kept. Two explicit actions are available:
reconcile(request_key)finds the Stripe record without the lost id, reads it back and compares it. UNKNOWN becomes VERIFIED only when that record compares VERIFIED. It also settles PENDING requests once Stripe reports a final status.retry_same_key(request_key)sends the request again with the same idempotency key, so one object exists afterwards. It is refused unless the state is UNKNOWN, and the policy is checked again first. Stripe keeps idempotency keys for a limited time, at least 24 hours, so use it promptly.
Status mapping#
| Stripe status | State |
|---|---|
Payout paid | VERIFIED if the record matches |
Payout pending, in_transit | PENDING |
failed, canceled | MISMATCH |
A different amount, currency or request id is MISMATCH. A missing field is UNKNOWN.
Receipts and state#
Receipts go to <state_dir>/receipts.ndjson, signed with the local seed, and verify with verdock verify. They hold the operation, amount, currency, counterparty, request id, provider object id, state and policy hash. They do not hold keys, response bodies or error text. State is in <state_dir>/adapters.sqlite3 in Python and in JSON files in Node. A chain written by one language verifies in the other.
Proof from a test mode run#
On 17 November 2026 a Stripe test mode call produced a verified refund. The adapter read the object back from Stripe and marked it VERIFIED. The run file is data/runs/stripe_test_2026-11-17.json. It holds no key.