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

A walk through the [Stripe Customer Operations pack](/docs/packs/stripe-customer-operations) 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](/docs/packs/stripe-customer-operations/connectors)).

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.

```bash
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

```bash
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.

```bash
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

```bash
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`.

```bash
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.

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](/docs/packs/stripe-customer-operations/failures) lists every code the pack can return
and what to do about each; the [adjust_invoice page](/docs/packs/stripe-customer-operations/adjust-invoice) 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.
