Download the PHP package kosovopay/php-sdk without Composer

Table of contents

• Why this SDK
• Requirements
• Installation
• Authentication & client setup
• Quickstart
• Core concepts
  • Minor units
  • Hosted vs. direct checkout
  • Idempotency
  • API versioning
• Payments
• Refunds
• Banks
• Currencies & FX rates
• Account (me)
• Webhooks
  • Verifying a webhook
  • Framework integration
  • Event types
  • Managing webhook endpoints
• Helpers
  • Money formatting & conversion
  • Local amount validation
• Error handling
  • Exception hierarchy
  • Error codes
• Type reference
• Retries, timeouts & resilience
• Testing
• Development
• Versioning & support
• License

Why this SDK

Requirements

• PHP 8.2 or higher
• ext-bcmath (optional) — used for exact decimal FX math in Money::convert(); the SDK falls back to native float math when it is absent
• ext-json (bundled with PHP)

Installation

That's it — no service providers, no config publishing. The client is a plain object you construct with your API key.

Authentication & client setup

Authenticate with a secret key from your KosovoPay dashboard. Keys are environment-scoped — sk_test_… for the test sandbox, sk_live_… for production.

The constructor accepts the full configuration surface; every argument after the key is optional and shown here with its default:

Never hard-code a live key. Load it from the environment or your secrets manager:

Quickstart

Create a hosted checkout and redirect the buyer to KosovoPay's payment page:

When the buyer finishes, KosovoPay sends a payment.captured webhook and redirects them to your successUrl.

Core concepts

Minor units

All monetary amounts are integers in the currency's minor unit — cents for EUR/USD, etc. There are no floats anywhere in the money path, which eliminates rounding drift.

Use Money::format() to render a minor-unit integer back to a human string.

Hosted vs. direct checkout

The SDK supports two checkout modes via the CheckoutMode enum:

Idempotency

Every mutating call (payments->create, refunds->create) accepts an optional idempotency key. If you omit it, the SDK generates a ULID automatically, so an in-flight retry never creates a duplicate charge. Supply your own key (e.g. your order ID) to make the operation idempotent across your retries too:

A key is valid for 24 hours. Reusing it with a different payload raises an IdempotencyException.

API versioning

The API is date-versioned. The SDK pins a version via the Kosovopay-Version header (default 2026-06-01) so the response shape never changes underneath you. Upgrade deliberately by bumping apiVersion in the constructor after reading the changelog.

Payments

Create — hosted checkout

Create — direct checkout

You select the bank; KosovoPay returns a redirect straight to it. bankCode is required in this mode.

The params object validates itself on construction. Passing mode: Direct without a bankCode, a non-positive amount, or a non-HTTP(S) successUrl throws InvalidArgumentException before any network call.

Retrieve

List & paginate

payments->all() returns a lazy iterator that transparently walks every page using cursor pagination — you never touch starting_after:

Filter options on ListPaymentsParams: status, bankCode, currency, merchantReference, createdGte, createdLte, limit, startingAfter, endingBefore.

Timeline

A chronological audit trail for a single payment, returned as a typed Collection<TimelineEvent>:

Cancel

Cancelling a payment that is no longer cancelable raises PaymentNotCancelableException.

Refunds

Create

Omit amount for a full refund; pass a value in minor units for a partial refund.

Not every bank supports partial refunds. Check $bank->capabilities->refunds->partial first (see Banks) — a partial refund to an unsupported bank raises PartialRefundUnsupportedException. Refunding more than the remaining balance raises RefundExceedsRemainingException.

Retrieve

List

Banks

Supported banks: BankCode::Procredit, BankCode::Procard, BankCode::Onefor.

Currencies & FX rates

Pair the rate with Money::convert() for exact minor-unit conversion.

Account (me)

Identify the key in use — its team, environment, usable banks and default currency:

keyPrefix is the only key material safe to log — it identifies the key without exposing the secret.

Webhooks

KosovoPay notifies your server of events (a captured payment, a succeeded refund) by POSTing a signed JSON event to your endpoint. Always verify the signature before trusting the payload.

Verifying a webhook

constructEvent() does three things: verifies the HMAC-SHA256 signature in constant time, enforces a 5-minute replay window on the timestamp, and decodes the raw body into a typed Event. The signed payload is "{timestamp}.{raw_body}" — which is why you must verify against the unmodified request body.

The signature header is exposed as a constant if you need it: Webhook::SIGNATURE_HEADER ("Kosovopay-Signature"). Adjust the replay tolerance with the fourth argument: Webhook::constructEvent($payload, $sig, $secret, tolerance: 600).

The decoded Event exposes id, type, created, livemode, apiVersion, the raw object, and previousAttributes. Use $event->asPayment() / $event->asRefund() to hydrate the affected resource into its typed DTO, and $event->createdAt() for a DateTimeImmutable.

Framework integration

Laravel

Symfony

Event types

Any event type added in the future arrives as WebhookEventType::Unknown — handle it with a default arm rather than a crash.

Managing webhook endpoints

Register, list, rotate, and delete endpoints programmatically:

Helpers

Money formatting & conversion

Local amount validation

Catch amount_below_minimum / amount_step_invalid before a round-trip by checking an amount against a bank's live capabilities:

Error handling

Every non-2xx response is converted into a typed exception. Catch the specific subclass you care about, or the KosovoPayException base for a catch-all. Every exception carries the full error envelope.

Every KosovoPayException exposes:

Exception hierarchy

Resolution order: an exact code match wins; otherwise the error type family is used; otherwise it falls back to ApiException. An unrecognised code from a newer API never crashes the SDK.

Error codes

Type reference

Enums

Enums marked with Unknown are forward-compatible: any value the platform introduces later decodes to Unknown rather than throwing. Always include a default/Unknown arm when matching on them.

Key response objects

Payment — id, status: PaymentStatus, mode: BankMode, amount, amountCaptured, amountRefunded, currency: CurrencyCode, bankCode: ?BankCode, merchantReference, description, payer: ?Payer, lineItems, metadata, fx: ?Fx, lastError, expires, captured, created, refunds, checkoutMode: ?CheckoutMode, hostedUrl, redirectUrl · methods: createdAt(): DateTimeImmutable

Refund — id, payment, amount, status: RefundStatus, reason: ?RefundReason, failureReason, created, succeededAt · methods: createdAt(): ?DateTimeImmutable

Bank — code: BankCode, displayName, logoUrl, enabled, modes, capabilities: BankCapabilities BankCapabilities — currencies: list<CurrencyCode>, minAmount, amountStep, refunds: RefundCapability RefundCapability — supported: bool, partial: bool

Currency — code: CurrencyCode, name, symbol, decimals, isDefault Rate — from: CurrencyCode, to: CurrencyCode, rate: string, syncedAt, stale Me — team: Team, mode: BankMode, keyPrefix, enabledBanks: list<BankCode>, defaultCurrency: ?CurrencyCode WebhookEndpoint — id, url, description, enabledEvents: list<WebhookEventType>, status, mode: BankMode, created, secret Event — id, type: WebhookEventType, created, livemode, apiVersion, data, object, previousAttributes · methods: asPayment(), asRefund(), createdAt()

Single-page lists (banks, currencies, webhookEndpoints, payment timeline) return a typed Collection<T> implementing Countable and IteratorAggregate — iterate it directly, call ->count(), or grab ->all() / ->data for the array. Paginated lists (payments, refunds) return a lazy iterator instead.

Retries, timeouts & resilience

The connector retries transient failures with exponential backoff, governed by maxRetries (default 3) and an internal 500 ms base interval (→ ~0.5s, 1s, 2s).

Because the SDK auto-attaches an idempotency key to every mutating call, your create operations are retried safely out of the box.

Tune timeouts via the constructor (connectTimeout, requestTimeout).

Testing

The client is backed by a Saloon connector, so you can swap in a MockClient and assert against requests — no network, fully deterministic:

Development

The codebase is held to PHPStan level max with zero suppressions — no @phpstan-ignore, no assert()-to-silence, no blind casts. Decoded JSON is narrowed through a dedicated coercion layer so types are real, not asserted.

Versioning & support

• The SDK follows semantic versioning. Breaking changes only land in a new major.
• The API is date-versioned independently and pinned via the Kosovopay-Version header — your integration won't shift under you when the platform evolves.
• Found a bug or need help? Include the requestId from the relevant KosovoPayException — it lets support trace the exact call.

License

KosovoPay License 1.0 — free to use, including commercially, at no charge. Modifying, forking, redistributing, or reverse-engineering the SDK is not permitted; it is maintained solely by KosovoPay. See LICENSE.