REST API. 272 endpoints. One token.

Quickstart

Get your first routing decision back in under five minutes. You'll need a Penumbra account and a sandbox API key from the dashboard.

Below: the same first request, in six languages.

curl https://api.penumbrahq.com/v1/routing/decide \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 124700,
    "currency": "USD",
    "card_bin": "424242",
    "mcc": "5812",
    "merchant_id": "mer_a4b9c2e1"
  }'

import Penumbra from '@penumbra/node';

const penumbra = new Penumbra(process.env.PENUMBRA_KEY);

const decision = await penumbra.routing.decide({
  amount_cents: 124700,
  currency: 'USD',
  card_bin: '424242',
  mcc: '5812',
  merchant_id: 'mer_a4b9c2e1',
});

console.log(decision.chosen.processor); // 'adyen'

import penumbra
import os

penumbra.api_key = os.environ["PENUMBRA_KEY"]

decision = penumbra.Routing.decide(
    amount_cents=124700,
    currency="USD",
    card_bin="424242",
    mcc="5812",
    merchant_id="mer_a4b9c2e1",
)

print(decision.chosen.processor)  # 'adyen'

import "github.com/penumbrahq/penumbra-go"

client := penumbra.NewClient(os.Getenv("PENUMBRA_KEY"))

decision, err := client.Routing.Decide(ctx, &penumbra.DecideParams{
  AmountCents: 124700,
  Currency:    "USD",
  CardBIN:     "424242",
  MCC:         "5812",
  MerchantID:  "mer_a4b9c2e1",
})

require "penumbra"

Penumbra.api_key = ENV["PENUMBRA_KEY"]

decision = Penumbra::Routing.decide(
  amount_cents: 124700,
  currency:     "USD",
  card_bin:     "424242",
  mcc:          "5812",
  merchant_id:  "mer_a4b9c2e1",
)

require_once 'vendor/autoload.php';

\Penumbra\Penumbra::setApiKey(getenv('PENUMBRA_KEY'));

$decision = \Penumbra\Routing::decide([
  'amount_cents' => 124700,
  'currency'     => 'USD',
  'card_bin'     => '424242',
  'mcc'          => '5812',
  'merchant_id'  => 'mer_a4b9c2e1',
]);

SDKs & libraries

Officially maintained client libraries. All track the same API surface; new endpoints land in every SDK within one release.

Authentication

Every request carries a bearer token in the Authorization header. Tokens are environment-scoped, scope-restricted, and rotatable.

Key types

Rotation

Rotate from Settings → API keys. Revocations propagate to all edge nodes in under 60 seconds. We recommend rotating live keys quarterly and immediately after any suspected exposure.

Errors & retries

Standard HTTP status codes. 2xx success, 4xx client error, 5xx server error. Every error body has a type, a human-readable message, and a request_id you can quote to support.

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_card_bin",
    "message": "card_bin is required for card-not-present routing decisions",
    "request_id": "req_8f3d2a17b4c19",
    "doc_url": "https://penumbrahq.com/docs/errors#missing_card_bin"
  }
}

Safe to retry: any 5xx, plus 429 (rate limit) and 409 (idempotency conflict mid-write). Use exponential backoff starting at 250ms, max 30s.

Not safe to retry without idempotency keys: any 2xx followed by a network error. The request may have succeeded server-side. Always include an Idempotency-Key header on write endpoints.

Rate limits

Per-key, sliding-window. Limits scale with tier; defaults below.

Limits surface in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Exceed the limit and you get a 429 with a Retry-After header in seconds.

Idempotency

Every write endpoint accepts an Idempotency-Key header. Send the same key with the same payload and we'll return the cached response — never double-charge, never double-publish. Keys are remembered for 24 hours.

curl https://api.penumbrahq.com/v1/routing/execute \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: order_a4b9c2e1_attempt_1" \
  -d '{...}'

UUIDs work; opaque order IDs work better because they're deterministic if you retry from your application code.

Pagination

Cursor-based, forward and backward. List endpoints return up to 100 records per page by default.

GET /v1/transactions?limit=50&starting_after=txn_8f3d2a17

// Response
{
  "object": "list",
  "data": [...],
  "has_more": true,
  "next_cursor": "txn_d12e54b8"
}

Routing

The routing engine scores every connected processor on approval probability, latency, and cost. Submit a transaction shape and get a ranked recommendation in milliseconds. Or have us submit it for you.

Decide response

{
  "decision_id": "dec_4Ag8nP2",
  "chosen": {
    "processor": "adyen",
    "approval_probability": 0.956,
    "expected_cost_bps": 241,
    "latency_ms_p50": 12
  },
  "runner_up": { "processor": "stripe", "approval_probability": 0.951 },
  "reason": "adyen_lower_cost_at_equivalent_approval",
  "policy_id": "pol_default"
}

Transactions

List, retrieve, and inspect every charge processed through Penumbra. Each transaction carries the original routing decision and the response from the processor.

Filter by processor, status, amount range, time window, MCC, card brand. Each row exposes the routing decision_id so you can replay the decision against current policies.

Disputes

The disputes engine ingests carrier notifications, assembles evidence, drafts the rebuttal, and submits when you approve. Stripe, Adyen, Worldpay, NMI all supported as submission targets.

Ledger

Double-entry immutable ledger with full chain-of-custody. Every transaction, payout, fee, refund, reserve adjustment writes journal entries you can audit. Built on the same accounting primitives as the operator dashboard.

Payouts

Schedule, inspect, or override payouts to merchants and to platform-fee accounts. ACH, Same-Day ACH, FedNow when sponsor-bank enrollment closes, and USDC settlement via Circle across five chains.

Merchants

Submit boarding applications, retrieve KYB/risk decisions, manage MIDs across the processors a merchant boarded with. Penumbra holds a thin merchant-identity record; PSP underwriting decisions are passed through.

Webhooks

Subscribe to any of the 41 canonical Pen.v1 events. HMAC-SHA256 signed, retried with exponential backoff up to 24 hours, 99.9% delivery SLO.

Full event catalogue with payloads at Webhook events.