Download the PHP package bankplanet9/milkyway-payments without Composer

MilkyWay Payments SDK for PHP

Official PHP client for the MilkyWay Payments API (/payments/v1) — the partner-facing API banks use to initiate, quote, track, and cancel cross-bank payments.

Batteries included:

• Keycloak client-credentials auth with in-memory token caching and automatic refresh (plus a one-shot refresh-and-replay on 401).
• Retries with exponential backoff + jitter on transient failures (5xx, 408, network), while deterministic errors (400/401/402/404) are never retried.
• Typed models & exceptions — money is brick/math BigDecimal (never float), status is a backed enum, and each HTTP error maps to a specific exception type.
• Client-agnostic — built on PSR-18 (HTTP client) and PSR-17 (factories) with php-http/discovery auto-discovery, so you can plug in Guzzle, Symfony HttpClient, or anything else.

Requires PHP 8.1+.

Install

You also need a PSR-18 client and PSR-17 factories. If your project does not already provide them, install a pair the SDK can auto-discover, e.g.:

Quick start

Bring your own HTTP client

Money & precision

All monetary fields (amountCredit, amountDebit, rate, commission) are Brick\Math\BigDecimal. The API encodes money as raw JSON numbers; the SDK reads those values from their literal textual form and builds BigDecimal from the string, so no binary-float rounding ever touches your amounts — and the original scale (e.g. 100.00) is preserved on the way out, too.

The data field

Each service requires extra per-partner fields (sender name, document number, birthday, …) in the data array. Which keys are required depends on your serviceId and the recipient bank — look them up in the Услуги registry at https://milkyway-docs.stage.planet9.ae. The server validates data against the service's JSON Schema during precheck, so a missing field is rejected before any money moves.

Errors

Every API error throws a subclass of MilkywayApiException (carrying getStatusCode() and the server's message via getMessage() / getResponseBody()):

Retries & idempotency

Transient failures (5xx, 408, network exceptions) are retried automatically with exponential backoff + jitter, tunable via MilkywayOptions (maxRetries, retryBaseDelay, requestTimeout). Deterministic 4xx responses are never retried.

pay() is only auto-retried when you supply an idempotencyKey — without one, a retry could create a duplicate payment, so the SDK sends it exactly once.

Configuration

Note: per-attempt timeout is honored by the underlying PSR-18 client — configure it on the client you pass in (e.g. Guzzle timeout), since PSR-18 has no portable timeout API.

Building from source

Releasing

Releases are fully automated by semantic-release on every push to main:

1. Conventional commits are analysed (feat: → minor, fix:/perf: → patch, ! / BREAKING CHANGE → major). No releasable commits → no release.
2. A GitHub release + vX.Y.Z tag is created with generated notes.
3. Packagist picks up the new tag automatically and publishes the new version.

There is no build artifact and no registry token for PHP — the git tag is the release, and Packagist syncs from it via a GitHub webhook.

One-time Packagist setup (maintainers)

Do this once so step 3 above works:

1. Sign in at https://packagist.org and Submit the repository URL https://github.com/bankplanet9/milkyway-php-sdk to register the bankplanet9/milkyway-payments package.
2. Enable auto-updates so each tag syncs automatically. Easiest: install the Packagist GitHub application (Packagist → your package → Settings shows the exact webhook/hook instructions), or add the GitHub service hook with your Packagist API token. Once connected, every vX.Y.Z tag pushed by semantic-release appears on Packagist within seconds.

No secrets are stored in CI; the release job only needs the default GITHUB_TOKEN.

License

MIT — see LICENSE. Copyright (c) 2026 Planet9.