Download the PHP package la-souris/credit-check-sdk without Composer

Credit Check SDK

The provider-agnostic core of the credit-check monorepo: the CreditChecker contract, a small applicant/affordability domain modelled as typed value objects, a normalised result model, an exception hierarchy, and small support helpers. Framework-free — no HTTP client, no framework.

The domain deliberately models only what every bureau needs. Supplier-specific vocabulary and supplier-specific fields belong in the provider package, behind its own mapper — see credit-check-edr for how that is done.

The contract

Every provider implements LaSouris\CreditCheck\Sdk\Provider\CreditChecker:

Each call answers with its own flattened response class — no shared envelope, no ->data indirection. Every response still carries the same two fields plus its own named ones:

$provider and $raw being on every response class means provider identity and the untouched body are available everywhere, not only on the calls whose payload happens to carry them — reading a field the SDK does not model is the same gesture on every call, with no drop into the provider package.

Credit checks are asynchronous: submitCheck() hands the applicant(s) over and returns a reference immediately while the bureau evaluates in the background; poll getResult() with that reference, or use getChangedChecksSince() to discover which checks changed since a given moment.

Three methods is the whole contract. What a provider is — its name, the countries it assesses, the currencies it accepts and the operations it can perform — is not behaviour, so it is declared once with the #[Provider] attribute rather than implemented as four more methods:

capabilities defaults to [Capability::CREATE_CHECK, Capability::GET_RESULT]. Operations a provider does not advertise throw UnsupportedOperationException.

Read it back with ProviderCapabilities::of(), which takes an instance or a bare class name — so discovery needs no construction and no credentials, which is how the framework packages build their registries. Results are cached per class, so the reflection happens once per process:

A class without the attribute throws MissingProviderAttributeException. The attribute is inherited, so a shared base class may declare it for its subclasses.

The domain

• Request (Request\CreateCreditCheck): a reference string (not promoted to a public property — pass it positionally, don't rely on $request->reference), one or more CreditCheck\Applicants passed variadically (not as an array), and a CreditCheck\Subject (financed amount + term + product label/variant). primaryApplicant() returns the first one.
• Applicant (CreditCheck\Applicant): wraps two Applicant\Persons — person and partner, both required, neither nullable.
• Person (Applicant\Person): identity (initials, firstName, surname, gender, dateOfBirth), a ContactInformation (e-mail + phone) and an Address, plus displayName().
• Address (Applicant\Address): country as an ISO 3166-1 alpha-2 string, a single houseNumber string so suffixed numbers ("12A", "3-bis") survive intact, street, postalCode, city, and a plain occupants count.

Monetary amounts use the moneyphp/money library (Money\Money / Money\Currency) — integer minor units, no float rounding errors.

Phone numbers are libphonenumber's own libphonenumber\PhoneNumber, not a wrapper — parse once and pass it around:

ContactInformation validates the number against libphonenumber's metadata (parsing alone only proves the input was well-formed) but stores it as-is. No formatting decision is baked into the domain — rendering is the caller's or the provider's call.

Support\Json::filter() drops null and [] values from an array — a small helper for providers serialising a payload where optional fields should be omitted rather than sent as null.

Everything a particular bureau needs beyond this — income and affordability figures, marital status, household flags, identification — lives in that bureau's provider package, behind its own mapper. See credit-check-edr for how that is done.

Building a request

Constructing a value object with input that violates its invariants throws Exception\InvalidArgumentException.

Reading a result

submitCheck() answers with a Response\CreateCreditCheckResponse — the provider name, the reference to poll with, and a Response\CheckStatus. No decision: the bureau has not evaluated anything yet.

getResult() answers with a Response\GetCreditCheckResponse:

Everything past status is optional, because bureaus differ in what they report and in how much is available before a check completes. $raw keeps the provider's own response intact, so a field the SDK does not model is still reachable without dropping to the provider package.

Decision is derived from the bureau's traffic light with Decision::fromTrafficLight($light, $completed): green/orange/red map to Approved/Referred/ Rejected, but only once the check has completed — a green light on a check still in progress is an interim reading, so it stays Pending. Only Approved and Rejected are isFinal(); Referred means someone at the bureau still has to look at it.

RejectionReason wraps the bureau's own code (e.g. ShortageOfIncome) and is deliberately not normalised — the sets differ per provider, and collapsing them would lose the detail needed to explain an outcome to an applicant.

ApplicantResult carries the per-person half of a decision (traffic light, monthly capacity); both fields are optional, since a bureau may screen a household jointly or finish screening before the affordability figures land.

Provider discovery

ProviderCapabilities::of() snapshots a provider for routing or UI, from an instance or a class name:

Providers enforce their own reach with the GuardsProviderReach trait, which reads the same attribute, so out-of-range input is rejected with a ProviderValidationException before any network call:

Exceptions

Everything the SDK or a provider throws extends Exception\CreditCheckException:

Providers translate their own transport/HTTP failures into this hierarchy (ProviderException::fromHttpStatus()), so callers handle credit-check errors uniformly regardless of supplier.

Providers

This package is useless on its own — pair it with a provider implementation such as la-souris/credit-check-edr, and with la-souris/credit-check-laravel or la-souris/credit-check-symfony for framework wiring.