Powered by Arrowhead Advisory Group
Developers

Common patterns. Working code.

Battle-tested blueprints for the most common ways teams plug Penumbra in. Each one ships with a working sample, the exact API calls, and a sandbox deploy you can fork.

~ 15 minEasy

Replace your single PSP with Penumbra

Low-risk migration. Drop Penumbra in front of your existing Stripe / Adyen / Worldpay account and route through us. Your existing PSP relationship stays intact; you add backups when you're ready.

Steps
  1. Generate a sandbox key and add your existing PSP's credentials in Settings → Processors
  2. Replace your direct PSP charge call with POST /v1/routing/execute
  3. Verify in sandbox: same approval rate, same processor
  4. Flip sk_test_ → sk_live_ when ready
MigrationSingle PSPNode / Python / Go
View blueprint →
~ 30 minEasy

Multi-PSP failover in three lines of config

Wire Penumbra to two or more processors. Define your primary plus ordered backups. When the primary degrades, we shift traffic automatically. Your code never knows which processor handled the charge.

Steps
  1. Add backup PSP credentials in Settings → Processors
  2. Create a routing policy: primary = Stripe, fallback = Adyen on decline or latency > 250ms
  3. Test by simulating a Stripe outage in sandbox
  4. Watch Penumbra promote Adyen automatically
FailoverMulti-PSPConfig-only
View blueprint →
~ 2 hoursMedium

White-label embed for vertical SaaS

Penumbra for Platforms blueprint. Embed the routing layer in your SaaS so your customers process payments through your brand. Subdomain plus custom theming plus sub-merchant onboarding.

Steps
  1. Provision a Penumbra for Platforms account in the dashboard
  2. Configure white-label theming (colors, logo, fav, email FROM)
  3. Point a subdomain at platforms.penumbrahq.com with a CNAME
  4. Drop the embedded onboarding component into your signup flow
  5. Customer wallets and money-flow ledger appear automatically
PlatformsEmbedWhite-label
View blueprint →
~ 45 minEasy

Sandbox-to-production cutover

How to flip from sk_test_ to sk_live_ with confidence. Smoke-test endpoints, webhook signature verification, rate-limit posture, alerting hookup. Ships with a 23-item pre-launch checklist.

Steps
  1. Run the production smoke-test suite in sandbox first
  2. Regenerate webhook signing secret for the live environment
  3. Verify HMAC verification in your handler against the live signing key
  4. Push real $1 test transaction; verify settlement webhook lands
  5. Tag the launch and start tailing logs
ProductionChecklist
View blueprint →
~ 1 hourMedium

Add USDC settlement to your fiat flow

Route fiat charges through Stripe / Adyen / Worldpay, settle the merchant in USDC via Circle. Five chains supported (Polygon / Ethereum / Solana / Base / Avalanche). Same API, additional rail.

Steps
  1. Enable Circle USDC in Settings → Rails
  2. Pick a default settlement chain per merchant (or per transaction)
  3. Configure the merchant's USDC receiving wallet
  4. Set the FX margin per the routing policy
  5. Charge as normal; settlement now lands on-chain
USDCCircleCrypto
View blueprint →
~ 20 minEasy

Webhook-driven reconciliation

Use Pen.v1 canonical events to reconcile your ledger automatically. Subscribe to transaction.* and settlement.*, write the events to your DB, never run a nightly batch job again.

Steps
  1. Register a webhook endpoint via POST /v1/webhooks/subscribe
  2. Subscribe to transaction.captured, refund.processed, settlement.completed
  3. Verify HMAC-SHA256 on every inbound
  4. Upsert into your DB keyed by the canonical event id
  5. Compare daily sums to processor statements; mismatches fire alerts
WebhooksReconciliation
View blueprint →
~ 90 minMedium

Auto-fight chargebacks

Let the AI chargeback engine assemble evidence, draft the rebuttal, and queue it for one-click approval. You set the policy (fight everything > $50, accept the rest), we draft and you approve.

Steps
  1. Enable Chargeback Defense in Settings (add-on, 20% of recovered amount)
  2. Define your fight-vs-accept policy: amount threshold, reason-code allow-list, win-probability floor
  3. Subscribe to chargeback.received webhooks for visibility
  4. Review the AI-drafted rebuttals in the dashboard; one-click submit
DisputesAI evidence
View blueprint →
~ 40 minMedium

BIN-based routing rules

Route a specific card brand or issuer to a preferred processor (e.g. Amex consumer cards through Stripe, Visa commercial through Worldpay). Lift approval rates by playing to each PSP's strengths.

Steps
  1. Define routing policies in dashboard or via POST /v1/routing/policies
  2. Add a BIN-range condition + target processor
  3. Test against the BIN-test sandbox
  4. Roll out to 10% of traffic, measure, then promote
RoutingBIN rulesApproval
View blueprint →

Want a blueprint that's not here?

Tell us what you're trying to wire and we'll either point you at a working sample or build one for you.

Tell us what you need