Skip to main content

Carbon Layer

PyPI CI Python License

Chaos engineering for payment flows.

Every company processing payments tests the happy path — payment succeeds, order fulfilled — and ships. What breaks in production is everything else: dispute spikes your system doesn't respond to, refund storms that break reconciliation, gateway errors that leave orders stuck, webhook sequences your handlers were never tested against.

Carbon Layer lets you simulate these failure modes against your own integration before your customers encounter them. Run a scenario, point it at your webhook endpoint, and see exactly what your system handles and what it doesn't.

Does your handler credit a payment twice?

Razorpay, Stripe and Cashfree all deliver webhooks at least once, so the same payment.captured can arrive more than once. A handler that doesn't dedupe returns 200 every time — so status codes alone will never show the bug. Carbon Layer checks the side effect itself:

carbon run dispute-spike --provider razorpay \
  --webhook-url http://localhost:8000/webhooks --webhook-secret $RAZORPAY_WEBHOOK_SECRET \
  --webhook-repeat 3 --webhook-order random \
  --verify-cmd "psql -tAc 'select count(*) from wallet_credits'" --ci
Side-effect verification (payment.captured)
  deliveries sent: 3000   unique events acked: 1000   counter: 0 -> 3000 (change 3000)
  FAIL: duplicate processing: payment.captured: 1000 unique events caused 3000 side effects; handler is not idempotent

No gateway account needed — webhooks are generated locally and signed exactly like the real provider's (including Razorpay's X-Razorpay-Event-Id, the key you should dedupe on).


Installation

Option A: Quick start (no database needed)

pip install carbon-layer

Works out of the box. Carbon Layer uses SQLite by default — data is stored in ~/.carbon/carbon.db. Nothing else to install or configure.

Option B: With PostgreSQL (if you already have it)

pip install carbon-layer[postgres]

Then set your connection string via a .env file or environment variable:

# .env file in your project directory
DATABASE_URL=postgresql://postgres:yourpassword@localhost:5432/carbon

Or with Docker:

docker run -d --name carbon-pg \
  -e POSTGRES_PASSWORD=carbon \
  -e POSTGRES_DB=carbon \
  -p 5432:5432 postgres:15

# then set:
DATABASE_URL=postgresql://postgres:carbon@localhost:5432/carbon

Both options support all features. You can start with SQLite and switch to PostgreSQL anytime by installing the extra and setting DATABASE_URL.

Option C: With pipx (isolated install)

pipx install carbon-layer

Option D: With Docker

docker run ghcr.io/pritom14/carbon-layer run dispute-spike --provider mock

Quickstart

# List available scenarios
carbon scenarios-list

# Run your first scenario
carbon run dispute-spike --provider mock

# View the report (use the run_id from the output above)
carbon report --run-id <run_id>

No payment gateway account needed. The mock adapter simulates the full payment lifecycle locally.


Webhook Simulation

The real value of Carbon Layer is testing your webhook handlers. Point it at your endpoint and it fires provider-specific webhook events — payment.captured, payment_intent.succeeded, PAYMENT_SUCCESS_WEBHOOK, ORDER_SUCCEEDED, and more — after the scenario runs. Payloads are signed exactly like real webhooks from each provider (Razorpay, Stripe, Cashfree, Juspay).

carbon run dispute-spike --provider mock --webhook-url http://localhost:8000/webhooks

The report shows how your endpoint responded for each event type — 2xx, 4xx, 5xx, or timeout. No payment gateway account required.


Scenarios

Scenario What it tests
dispute-spike 15% dispute rate — does your system respond and submit evidence?
payment-decline-spike 30% payment failure rate — does your retry and order state logic hold?
refund-storm Mass refunds on captured payments — does reconciliation break?
flash-sale High order and payment volume — does throughput hold?
gateway-error-burst Intermittent gateway errors — are orders left in inconsistent state?
min-amount Minimum paise transactions — are edge-case amounts handled correctly?
max-amount Large-value transactions — are limits and approvals handled correctly?
upi-timeout UPI payments stuck without terminal status — does your reconciliation catch it?
vpa-not-found Invalid UPI VPA failures — does your handler distinguish VPA errors from general failures?
mandate-rejection UPI autopay mandate rejections — does your handler notify the customer?
settlement-delay Refunds on captured-but-unsettled payments — does reconciliation handle it?

Parameter Overrides

Override scenario parameters at runtime without editing YAML:

carbon run dispute-spike --provider mock --set baseline_orders=500 --set dispute_rate=0.3

Use --set multiple times for multiple parameters. Unknown keys are ignored with a warning. Entity counts, rates and validation thresholds all follow the parameters (e.g. dispute-spike creates baseline_orders * dispute_rate disputes).


HTML Reports

Export a shareable HTML report after any run:

carbon report --run-id <run_id> --format html

Writes carbon_report_<run_id>.html to the current directory. Self-contained, no external dependencies — safe to share with your team or attach to an incident report.


Webhook Resilience Testing

Test how your webhook handler behaves under real-world failure conditions.

Idempotency (duplicate webhooks)

Fire each webhook multiple times to test whether your handler processes duplicates:

carbon run dispute-spike --provider mock --webhook-url http://localhost:8000/webhooks --webhook-repeat 5

Every repeat of an event carries the same event id (X-Razorpay-Event-Id for Razorpay; the payload id for Stripe/Juspay), just like a real provider retry.

A non-idempotent handler still answers 200, so add --verify-cmd to check the actual side effect. It takes any shell command that prints a number — a SQL count, a curl to an internal stats endpoint, a Redis GET:

carbon run dispute-spike --provider razorpay --webhook-url http://localhost:8000/webhooks \
  --webhook-repeat 5 --verify-cmd "psql -tAc 'select count(*) from wallet_credits'" \
  --verify-event payment.captured

Carbon Layer runs the command before and after delivery and compares the change with the number of unique events your endpoint acknowledged (2xx):

Result Meaning
PASS each event processed exactly once
FAIL: duplicate processing retries were processed as new events (double credit / double fulfilment)
FAIL: lost events events were acknowledged with 2xx but never processed

With --ci, a failed verification exits with code 1. The command runs right after the last delivery, so if your handler processes events asynchronously (queue/worker), point it at something that reflects completed work or add a wait (sleep 5 && psql ...).

Out-of-order delivery

Gateways don't guarantee webhook order. Test with randomized or reversed delivery:

carbon run dispute-spike --provider mock --webhook-url http://localhost:8000/webhooks --webhook-order random

Options: sequence (default), reverse, random.

Signature verification

Test whether your handler actually validates webhook signatures:

# Missing signatures — should your handler reject these?
carbon run dispute-spike --provider mock --webhook-url http://localhost:8000/webhooks --webhook-signature missing

# Corrupted signatures
carbon run dispute-spike --provider mock --webhook-url http://localhost:8000/webhooks --webhook-signature corrupted

# Signed with wrong secret
carbon run dispute-spike --provider mock --webhook-url http://localhost:8000/webhooks --webhook-signature wrong_secret

Options: valid (default), missing, corrupted, wrong_secret.


Webhook Replay

Replay stored webhook payloads from any previous run. Useful for regression testing after code changes:

carbon replay <run_id> --webhook-url http://localhost:8000/webhooks

CI/CD Integration

Use --ci to fail the build if any webhook returned 5xx or timed out:

carbon run dispute-spike --provider mock \
  --webhook-url http://localhost:8000/webhooks \
  --ci

Use --callback-url to POST a JSON run summary to your pipeline:

carbon run dispute-spike --provider mock \
  --webhook-url http://localhost:8000/webhooks \
  --callback-url http://localhost:8000/carbon/results \
  --ci

The callback payload includes pass/fail status, findings summary, and webhook delivery counts.

JSON output

Pipe results to jq, Datadog, Slack, or any tool:

carbon run dispute-spike --provider mock --webhook-url http://localhost:8000/webhooks --output json

Returns structured JSON with run status, findings, webhook delivery stats, and overall pass/fail.

Example GitHub Actions workflow

See examples/github-actions.yml for a copy-paste workflow that runs Carbon Layer on every PR.


Supported Payment Gateways

Carbon Layer generates provider-specific webhook payloads with correct signing for each gateway.

Provider Webhook Format Signing CLI Flag
Mock Razorpay-format HMAC-SHA256 --provider mock
Razorpay X-Razorpay-Signature HMAC-SHA256 --provider razorpay
Stripe Stripe-Signature: t=...,v1=... HMAC-SHA256 --provider stripe
Cashfree x-webhook-signature Base64(HMAC-SHA256) --provider cashfree
Juspay Authorization: Basic ... Basic Auth --provider juspay

Razorpay

carbon run dispute-spike \
  --provider razorpay \
  --api-key your_test_key \
  --api-secret your_test_secret \
  --webhook-url https://your-app.com/webhooks

Or set RAZORPAY_API_KEY and RAZORPAY_API_SECRET as environment variables.

Stripe

carbon run dispute-spike \
  --provider stripe \
  --stripe-key sk_test_xxx \
  --webhook-url https://your-app.com/webhooks

Or set STRIPE_API_KEY as an environment variable.

Cashfree

carbon run dispute-spike \
  --provider cashfree \
  --cashfree-id your_app_id \
  --cashfree-secret your_secret_key \
  --webhook-url https://your-app.com/webhooks

Or set CASHFREE_CLIENT_ID and CASHFREE_CLIENT_SECRET as environment variables.

Juspay

carbon run dispute-spike \
  --provider juspay \
  --juspay-key your_api_key \
  --juspay-merchant-id your_merchant_id \
  --webhook-url https://your-app.com/webhooks

Or set JUSPAY_API_KEY and JUSPAY_MERCHANT_ID as environment variables.

Mock (no credentials needed)

carbon run dispute-spike --provider mock --webhook-url http://localhost:8000/webhooks

Mock mode simulates the full payment lifecycle locally. Use this if you don't have test credentials — all 11 scenarios work out of the box.


Carbon Layer Pro (coming soon)

The open-source CLI covers 11 scenarios, 5 payment gateways, and webhook resilience testing. We're building a hosted Pro tier for teams that need more:

  • Scheduled runs — run scenarios on a cron, get notified when your handlers regress
  • PDF reports — export compliance-ready reports for audits and stakeholders
  • Compliance dashboards — track webhook handler reliability over time
  • Pro scenarios — RBI compliance checks, PCI readiness suite, 10k TPS load tests, multi-gateway failover, settlement reconciliation
  • Team management — shared runs, role-based access, audit logs

The free CLI stays free and open-source (Apache 2.0). Pro is a separate hosted product.

Join the waitlist: pritom14.github.io/carbon-layer/waitlist


License

Apache 2.0 — see LICENSE.

Metadata

Release files for carbon-layer 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for carbon-layer 0.7.0
File Size Uploaded Provenance Actions
carbon_layer-0.7.0.tar.gz 57.8 kB Without provenance Details for carbon_layer-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for carbon-layer 0.7.0
File Interpreter ABI Platform Actions
carbon_layer-0.7.0-py3-none-any.whl Python 3 none any Details for carbon_layer-0.7.0-py3-none-any.whl

Total release size: 126.3 kB

Release files / carbon_layer-0.7.0.tar.gz

Download URL carbon_layer-0.7.0.tar.gz
Size 57.8 kB
Tags Source
SHA-256 checksum
How to use checksums
c8ea3228758df44bd3f9ec37baed910f00d48ac7467c85178a1d0282b87f49d6
BLAKE2b-256 checksum
How to use checksums
049c963629d7825224e71a6e13447b69cfdae60baf95f7c2a869d228269f7472
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / carbon_layer-0.7.0-py3-none-any.whl

Download URL carbon_layer-0.7.0-py3-none-any.whl
Size 68.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4e363308c73af8dd67c81636edece2ace460a3384303347bbfebab77d1d38693
BLAKE2b-256 checksum
How to use checksums
a2ef627ec16dab92e7c9e3f17f259797da8894e9e04211514d076c1c5d83e198
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for carbon-layer 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page