VERDOCK

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.

ProviderEnvironment variable
StripeSTRIPE_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 UNKNOWN

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#

  1. Decides with the policy before any network call. A blocked or approval required action writes an adapter.blocked receipt and raises Refused. No request is sent.
  2. 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.
  3. Records the expectation in the outcome log and writes an adapter.admitted receipt.
  4. Sends the request once, with the request id as the Stripe Idempotency-Key.
  5. 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.outcome receipt 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
CreatePOST /v1/payouts
IdempotencyIdempotency-Key header
Request id in the recordmetadata[verdock_request_id]
Read backGET /v1/payouts/{id}
Find without the idList 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 statusState
Payout paidVERIFIED if the record matches
Payout pending, in_transitPENDING
failed, canceledMISMATCH

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.