Repository navigation
v0.1.0
Initial release.
Added
- Provider-neutral payment contracts:
PaymentGatewayInterfacewith the
optionalCapture,Cancel,ConfirmandRefundgateway interfaces, the
request objects they take, andPaymentIntent,PaymentAttempt,
RefundAttempt,PaymentFailureandObservedPaymentEventas results. - A minor-unit
Moneyvalue object withequals(),isGreaterThan()and
isLessThan()—equals()compares currency as well as amount, which is
what reconciliation needs when checking a provider amount against an order. PaymentStateandRefundStatewith an advisorycanTransitionTo()map.
RequiresPaymentMethodmodels a recoverable decline: a terminal state must
not absorb a status the provider can still move tosucceeded.- PSR-18 transport (
Psr18Transport),JsonRequestBuilderincluding
buildRawJson()for forwarding a signed document byte for byte,
FormRequestBuilderandJsonResponseDecoder, with a typed exception
hierarchy over the HTTP boundary. GatewayRegistry,PaymentGatewayRouterand a selection policy, so an
application routes by capability instead of by hard-wired provider name.- A webhook pipeline: validation, replay protection through a claim/complete
event store, event recognition, payload mapping, redaction, and either
durable queue acceptance or synchronous reconciliation. - Sealed webhook outcome types —
ProcessedWebhook,ReplayedWebhookEvent,
WebhookValidationFailed,UnknownWebhookEvent,UnsupportedWebhookEvent
andRejectedWebhookEvent— so an HTTP bridge picks its acknowledgement by
instanceofrather than by guessing. WebhookController, a PSR-7 adapter that answers with a status and an
outcome token only, never with a payload or a validation reason, and takes an
optional PSR-3 logger so a503failure leaves a trace.docs/cookbook.md/docs/cookbook.ru.mdand
docs/security-retention.md/docs/security-retention.ru.mdcovering
end-to-end recipes, credential handling and webhook retention boundaries.
Security
- A permanently unmappable payload is terminal, not retryable: a
MalformedResponseExceptionfrom a mapper becomesRejectedWebhookEvent
(HTTP 204), so one poison payload cannot drive the retry storm that gets an
endpoint disabled and loses the deliveries behind it. - A claim is finalised explicitly through
WebhookEventStoreInterface::complete().
Without a completion signal a store cannot tell an in-flight claim from a
finished one: expire claims and an already-handled event is processed again on
the next provider retry; never expire them and a claim abandoned by a killed
process answers every later delivery with a replay outcome, so the provider
stops retrying and the event is lost with no error anywhere. - An empty request body is reported as its own
empty_bodyoutcome rather than
as a signature failure, so a body-parsing middleware mounted ahead of the
webhook route is diagnosable from the response alone. sanitizedHeaders()andsanitizedRequestMetadata()redact credential
classes by name. The list is best-effort and does not replace a logging
policy.- Provider error text is capped at 1024 bytes, cut back to a character
boundary, before it travels inside an exception message;idempotencyKeyis
validated as a header token at the boundary that owns it, and it is never
generated for the caller.