Download the PHP package gardi/dcb-kit without Composer

dcb-kit

A small, framework-agnostic toolkit for direct carrier billing (DCB) in PHP — the part that's the same across every carrier: one gateway interface, normalized callback events, idempotent charging, and signature verification. Zero runtime dependencies.

I built and ran 20+ carrier-billing integrations across ~10 countries on a production platform (subscriptions, one-off charges, and millions of async billing callbacks). The carriers were all different — different APIs, different notification formats, different quirks — but the shape of the problem was always the same. dcb-kit is that shape, distilled. It is not any carrier's proprietary integration (those stay under NDA where they belong); it's the scaffolding you hang your own adapters on.

Install

The idea

A carrier integration always comes down to a few operations — subscribe a number, charge it, cancel — plus a stream of async notifications (activated, renewed, charged, out of balance, unsubscribed). Every carrier names these differently; dcb-kit normalizes them to one enum so the rest of your app never cares which carrier it's talking to:

Write a carrier

Implement one interface per carrier:

Or configure one instead of coding it

Most carriers are just a base URL + a status table + an auth scheme + a signature scheme. For those, skip the class — hand HttpCarrierGateway the moving parts:

The pieces that vary most between carriers are all strategies you pick:

• Auth (Gardi\DcbKit\Auth\*): BearerAuth, ApiKeyAuth, BasicAuth, QueryKeyAuth, NoAuth — or implement Authentication for request signing.
• Callback verification (Gardi\DcbKit\Verification\*): HmacVerifier (HMAC of the raw body) or NoVerification — or implement CallbackVerifier.
• Field names accept dot paths (data.transaction.id), so renamed and nested response/callback shapes need no code.

Carriers that still don't fit extend HttpCarrierGateway and override the one method that differs.

Or define every carrier in config

When the carriers are config-shaped, build the whole manager from an array — no per-carrier code at all:

auth.type is one of bearer / api_key / basic / query / none; verifier.type is hmac / none. This maps straight onto a Laravel/Symfony config file — adding a carrier becomes a config edit, not a code deploy.

Use it

Register your carriers and resolve them by name:

See tests/FakeCarrier.php for a complete reference gateway.

Resilience (optional)

Three opt-in decorators cover the production concerns — all composable with the above.

Retry transient failures — wrap your Transport. Retrying a charge is safe because the reference is the carrier's idempotency key, so the same reference is never a second charge:

Don't double-charge your own retries — wrap a gateway with an IdempotencyStore. A charge already completed under a reference is replayed from the store instead of charged again (failed charges aren't remembered, so they can be retried):

The shipped InMemoryIdempotencyStore is for tests / a single process — back the IdempotencyStore interface with Redis or a unique-indexed table in production. (This guards against your app repeating a charge; the in-flight case — you charged, the response was lost, you retry — is covered by the carrier's own reference idempotency.)

Handle a webhook in one call — resolve the carrier, verify the raw body, decode, and parse:

What's in the box

• CarrierGateway — the per-carrier interface.
• HttpCarrierGateway — a configurable base: stand up a carrier from a base URL + StatusMap + auth + verifier + (dot-path) field names; override only the unusual bits.
• CarrierManager — register/resolve carriers by name (eager or lazy), or CarrierManager::fromArray() to build them all from one config array.
• Authentication (Auth\*) — pluggable outgoing-request auth: bearer, API key, basic, query key, or your own.
• CallbackVerifier (Verification\*) — pluggable callback verification: HMAC of the raw body, none, or your own.
• CallbackEvent / CallbackType / StatusMap — normalized notifications + the status table that feeds them.
• Transport — the HTTP seam (bring your own client; keeps the kit dependency-free).
• Money, SubscriptionResult, ChargeResult, CallbackUrl — small value objects.
• Signature — the constant-time HMAC primitive behind HmacVerifier.
• RetryingTransport — a Transport decorator: retry transient failures with exponential backoff.
• IdempotencyStore + IdempotentGateway — dedupe charges by reference (ships an in-memory store; bring your own for production).
• WebhookHandler — resolve + verify + parse an incoming carrier webhook in one call.

Limitations

Deliberately a toolkit, not a platform:

• No real carrier adapters ship with it. Carrier APIs are proprietary and under contract. HttpCarrierGateway gets a standard one running from config; unusual ones you finish by overriding a method.
• Idempotency is opt-in, and the shipped store isn't persistent. IdempotentGateway dedupes charges by reference, but InMemoryIdempotencyStore is single-process — back the IdempotencyStore interface with Redis or a unique-indexed table in production.
• Retries, not queueing. RetryingTransport handles transient failures; durable async work (queues/workers) is still yours to wire.

Development

License

MIT — see LICENSE.