Skip to content
Browse the documentation
Workflow packs

Stripe pack: from a test-mode key to a first verdict

From a Stripe sandbox's restricted key to a first verdict, command by command: connect, install, activate, act, push one fact, read PASS, then break it once.

Last changed Markdown versionllms.txt

A walk through the Stripe Customer Operations pack with a Stripe sandbox and nothing else: connect Stripe with a restricted test key, install the pack, let an "agent" (you, with curl) adjust an invoice, and read the verdict. It uses the adjust_invoice workflow because that one needs only Stripe and one pushed fact; the other four also read an order system or a help desk (connector requirements).

You need a CommitLayer workspace on the Builder plan or above in which you are an admin, and a Stripe sandbox. Nothing here moves money: a Stripe sandbox processes no payments, and CommitLayer only reads.

1. In Stripe: a restricted key for CommitLayer

In the sandbox, create a restricted API key with read on Refunds, Credit notes, Subscriptions, Invoices, Customers and Charges, and no other permission. A sandbox's restricted key starts with rk_test_. This is the only Stripe credential CommitLayer ever holds; the secret key used in steps 5 and 6 stays on your machine.

2. In the app: connect Stripe and create three keys

  1. Connections, add Stripe, paste the rk_test_ key. The connection turns healthy and its first sync starts by itself.
  2. Settings, API keys, create three keys: one with the full preset for the setup calls below, one with the recorder preset, and one with the evidence preset bound to the source messaging.

Both steps need a person with the admin role: an API key cannot create a connection or another key.

export COMMITLAYER_API="https://api.commitlayer.ai"
export SETUP_KEY="paste-your-full-key"
export RECORDER_KEY="paste-your-recorder-key"
export EVIDENCE_KEY="paste-your-evidence-key"

3. Dry-run the pack, then install it

curl -sS -X POST "$COMMITLAYER_API/v1/packs/stripe_customer_operations/dry-run" \
  -H "X-API-Key: $SETUP_KEY" -H "Content-Type: application/json" -d '{}'

The answer ends with "summary": {"total": 73, "ok": 73, "failed": 0}: every fixture case of the five workflows ran through the engine in your workspace and gave the verdict the pack expects. Nothing was written. If a call here answers 503 busy (it can while the connection's first sync is writing), it was not applied: send it again.

curl -sS -X POST "$COMMITLAYER_API/v1/packs/stripe_customer_operations/install" \
  -H "X-API-Key: $SETUP_KEY" -H "Content-Type: application/json" -d '{"confirm": true}'

The answer lists five contracts saved as drafts at version 1 and the calls that activate them. On the Developer plan it lists one, scop_refund_order: the refund workflow is open to every plan and the other four need Builder, and the Stripe connector this walk uses is not on Developer either.

4. Activate the one contract this walk uses

curl -sS -X POST "$COMMITLAYER_API/v1/contracts/scop_adjust_invoice/select?version=1" \
  -H "X-API-Key: $SETUP_KEY"

{"ok": true, "contract_id": "scop_adjust_invoice", "version": 1}. The same is the Activate button on the pack's page in the app.

5. In Stripe: an open invoice to adjust

With your sandbox's secret key, on your own machine, create a customer, an invoice item of 480.00 USD, an invoice that includes it, and finalize the invoice so that it is open. Stripe takes amounts in the smallest currency unit, so 480.00 USD is 48000.

export STRIPE_TEST_KEY="paste-your-sandbox-secret-key"

curl https://api.stripe.com/v1/customers -u "$STRIPE_TEST_KEY:" -d name="Walkthrough Customer"
export STRIPE_CUSTOMER="paste-the-cus-id-from-the-answer"

curl https://api.stripe.com/v1/invoiceitems -u "$STRIPE_TEST_KEY:" \
  -d customer="$STRIPE_CUSTOMER" -d amount=48000 -d currency=usd

curl https://api.stripe.com/v1/invoices -u "$STRIPE_TEST_KEY:" \
  -d customer="$STRIPE_CUSTOMER" -d collection_method=send_invoice -d days_until_due=30 \
  -d pending_invoice_items_behavior=include
export STRIPE_INVOICE="paste-the-in-id-from-the-answer"

curl -X POST "https://api.stripe.com/v1/invoices/$STRIPE_INVOICE/finalize" -u "$STRIPE_TEST_KEY:"

The last answer should show "status": "open".

6. The agent acts: record the action, then issue the credit note

Record first. An effect counts only at or after the action's requested_at, which is the moment of this call, so the action is recorded before the tool runs. The approval here is a reduction of 120.00 USD; the action carries major units.

curl -sS -X POST "$COMMITLAYER_API/v1/actions" \
  -H "X-API-Key: $RECORDER_KEY" -H "Content-Type: application/json" \
  -d "{
    \"action_id\": \"adjust:$STRIPE_INVOICE\",
    \"contract_id\": \"scop_adjust_invoice\",
    \"contract_version\": 1,
    \"subject_id\": \"$STRIPE_INVOICE\",
    \"subject_kind\": \"invoice\",
    \"params\": {\"amount\": 120.0, \"currency\": \"usd\", \"invoice_id\": \"$STRIPE_INVOICE\", \"reason\": \"duplicate_line_item\"},
    \"environment\": \"test\"
  }"

"environment": "test" is what makes a test-mode key the right evidence: an action recorded as production (the default) and judged on test-mode Stripe records reads UNKNOWN with evidence_mode_mismatch, never PASS or FAIL. A test action is metered like any other.

201. The verification in the answer is pending: nothing has been seen for this invoice yet. Its provisional verdict is UNKNOWN with identity_unmatched, because the connector has not read the new invoice; had a sync run since step 5 it would be a provisional FAIL naming the two effects still missing. Now the adjustment itself, in Stripe, as a credit note of 12000 against the invoice:

curl https://api.stripe.com/v1/credit_notes -u "$STRIPE_TEST_KEY:" \
  -d invoice="$STRIPE_INVOICE" -d amount=12000 -d reason=order_change

7. Push the one fact Stripe does not hold

The contract also expects the customer to have been told. That comes from the system that sent the message, through the evidence key:

curl -sS -X POST "$COMMITLAYER_API/v1/facts" \
  -H "X-API-Key: $EVIDENCE_KEY" -H "Content-Type: application/json" \
  -d "{\"facts\": [{
    \"source\": \"messaging\",
    \"subject_id\": \"$STRIPE_INVOICE\",
    \"subject_kind\": \"invoice\",
    \"fact_type\": \"customer_notified\",
    \"occurred_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",
    \"attributes\": {\"channel\": \"email\"}
  }]}"

201 with "ingested": 1, "linked": 0, and beside them one result per record: its id, the evidence trust class it got and why, and whether it is eligible for the contract. This is the step a first integration misses twice over. First, the fact has to come from an evidence key: pushed with the recorder key it is refused (403 insufficient_scope), and pushed with a full key it is classed agent_self_report and never counts. Second, a pushed record is eligible only once its source is attested for the key that sent it: in the app, open Connections, Evidence pipeline, and on the messaging row of the evidence key choose Attest (an Owner or Admin, signed in), check the confirmation (the details are behind "Review what this means") and confirm. That is the record's evidence trust class becoming backend_attested; the action is re-verified by itself. Until then the verdict carries effect_below_trust:messaging.customer_notified.

8. Sync Stripe and read the verdict

The Stripe connector syncs on its own schedule; ask for a sync now rather than wait:

curl -sS "$COMMITLAYER_API/v1/connections" -H "X-API-Key: $SETUP_KEY"
export STRIPE_CONNECTION="paste-the-id-of-the-stripe-connection"

curl -sS -X POST "$COMMITLAYER_API/v1/connections/$STRIPE_CONNECTION/sync" \
  -H "X-API-Key: $SETUP_KEY" -H "Content-Type: application/json" -d '{}'

{"job_id": "…"}; the sync runs in the background and takes a few seconds on a small sandbox. Then:

curl -sS "$COMMITLAYER_API/v1/actions/adjust:$STRIPE_INVOICE/wait?timeout=30" \
  -H "X-API-Key: $RECORDER_KEY"

"status": "settled", and under lenses both outcome and policy read "verdict": "PASS" with the codes effect_observed:stripe.credit_note and effect_observed:messaging.customer_notified. summary.headline says the same in a sentence, and facts lists the Stripe records the verdict rests on. If it still reads pending, the sync has not finished: run the last command again.

Read through /wait, as here. The plain GET /v1/actions/{id} evaluates nothing: until a wait has seen the action settle (or the re-check at the end of the window has run) its lenses are still the ones stored in step 6, UNKNOWN with identity_unmatched, under a status and a summary.headline that are rebuilt from the facts and already read settled and PASS.

9. Break it once

Do steps 5 and 6 again for a second invoice, and this time record an approval of 100.0 while the credit note is still 12000. After the push and the sync, the same read returns outcome PASS and policy FAIL with effect_attr_mismatch:stripe.credit_note.amount: the adjustment happened, and it was not the one approved. Leave amount out of the action altogether and the policy lens reads UNKNOWN with param_missing:amount: the checks that read the amount did not run. Reading a verdict lists every code the pack can return and what to do about each; the adjust_invoice page lists everything this contract checks.

How this page was checked

The commands to CommitLayer (steps 3, 4, 6, 7 and 8) were run in this order against the API, and are run again by the test suite on every change, with a stand-in answering the four lists the Stripe connector reads (refunds, credit notes, subscriptions, invoices) in the shape Stripe returns them. The verdicts quoted in steps 8 and 9 are what the engine returned in that run. The same commands were also run with bash and curl against an API process on a local port, with the same stand-in for Stripe, and gave the same verdicts. The commands to Stripe (steps 5 and 6) follow Stripe's API reference as it read on 13 November 2026 and were not run against Stripe: no Stripe key was available when this page was written. The clicks in steps 1 and 2 were not made in a browser; the routes behind them were called with a signed-in session.