1.1.3

🚀 UPC 1.1.3

Adds the authorization / capture / cancellation payment lifecycle to UnifiedApiPaymentService, and
fixes payments failing for customers browsing over IPv6. No breaking changes; a plugin that upgrades
and changes nothing is unaffected.

🐛 Fixes

• 🌐 IPv6 browser IP no longer rejected — the Unified API caps browser.ip at 15
  characters (an IPv4 maximum) and rejects an IPv6 address, so payments from IPv6 clients failed.
  BrowserDto::toArray() now serializes any ip containing a : as 0.0.0.0, for both
  HostedFieldDto and PaymentDto. The public BrowserDto::$ip keeps the caller's original value;
  only the request payload changes.

✨ Added

• 🔐 Authorization — no new call: it is createPayment() with CommonFieldsDto::$capture = false,
  optionally with the new partialAuthorization flag and/or authorizationType
  (AuthorizationType::PRE_AUTHORIZATION / FINAL_AUTHORIZATION). PaymentOutput now also exposes
  maxCaptureDate and remainingCapturableAmount for an authorization-only creation (PRE-3670).
• 💳 UnifiedApiPaymentService::capturePayment() — full or partial capture, immediate or deferred,
  one or several times, returning a CaptureOutput.
• 🚫 UnifiedApiPaymentService::cancelPayment() — full (default) or partial cancellation of a
  payment or authorization, returning a CancellationOutput.
• ⚠️ 13 new exception subtypes so a plugin can catch precisely instead of parsing a generic
  ApiException:
  • Business outcomes normalized from the Unified API response: AuthorizationExpiredException,
    PaymentAlreadyCapturedException, PaymentAlreadyCancelledException,
    AmountExceedsAvailableException, OperationConflictException,
    PartialCancellationNotAllowedException, PaymentNotVoidableException,
    PaymentNotCapturableException, MultipleCaptureNotAllowedException. An issuer refusal reuses the
    existing CardOperationException.
  • Local pre-call validation (no HTTP request sent): InvalidCaptureRequestException /
    CaptureAmountException and InvalidCancellationRequestException /
    CancellationAmountException — empty orderId/description, non-positive amount, or a missing
    currency alongside a partial amount.

🔁 Compatibility

Upgrading from 1.1.2 with no plugin-side change is a no-op: no existing signature, contract or
exception changed, and the new CommonFieldsDto properties default to null. Idempotency across
replayed capture/cancel requests remains the consuming plugin's job (IPaymentRepository / ILock);
UPC only normalizes the API's "already happened" signals into distinct exception types.

✅ Quality

PHPStan level 8, PHP-CS-Fixer, PHPUnit and CI verifying PHP 7.1–8.2 compatibility. New unit tests cover
every new class and the error-classification paths, plus two integration tests that assert the API's own
rejection against the shared staging fixture payment (proving auth/URL/JSON wiring without mutating it).

📋 Requirements

• PHP ≥7.4 to install/develop (build-tooling floor only — shipped source runs on PHP 7.1)
• Runtime dependency: giggsey/libphonenumber-for-php

🔗 Full Changelog: 1.1.2...1.1.3

1.1.3-rc0

What's Changed

• PRE-3670: Add authorization, capture and cancellation operation by @ilajili in #35
• PRE-3713: fall back to 0.0.0.0 for an IPv6 browser IP by @jhoaraupp in #37

Full Changelog: 1.1.2-rc0...1.1.3-rc0

1.1.2

🚀 UPC 1.1.2

Additive release exposing the OpenID Connect id_token on TokenOutput, so a consuming plugin can
identify who authorized a connection — not just which account the resulting token authorizes.
No breaking changes; a plugin that upgrades and changes nothing is unaffected.

✨ Added

• 🪪 TokenOutput::$idToken — the id_token returned by an authorization-code exchange, the only
  place a logged-in person's identity surfaces. GET /account carries no email (its payload is
  id, company_ref, country, object, is_live, configuration, permissions,
  payment_methods and nothing else, verified live against several QA accounts), and the
  client_credentials token authenticates a machine, so it names no user either. A consumer wanting
  the merchant's address has to read the email claim off this token at login time.
• 🔓 OAuth2Client::requestToken() passes id_token through when the token-endpoint response
  carries one, instead of discarding it while constructing the TokenOutput.

♻️ Changed

• Nothing behavioural. idToken is a trailing 4th constructor argument defaulting to null, and
  a purely additive public property — every pre-existing 3-argument caller and every read of
  accessToken / expiresIn / tokenType is untouched.
• idToken is deliberately optional and unvalidated: requestToken() is shared by
  exchangeAuthorizationCode() and getClientCredentialsToken(), and only the former can ever
  produce an id_token, so asserting on it would reject a perfectly usable client-credentials
  response. UPC does not parse the JWT — consumers decode whichever claim they need.

🔁 Compatibility

Upgrading from 1.1.x with no plugin-side change is a no-op:

• TokenOutput is final, so nothing can have subclassed it with a 3-argument constructor.
• The new read is isset($data['id_token']) && \is_string(...) — it cannot throw and adds no failure
  path.
• No cache invalidation needed. TokenManager caches only the bare access-token string, never
  the object, so the token-cache format is unchanged. Nothing in UPC serializes, json_encodes or
  get_object_vars() a TokenOutput.
• idToken is non-null only when a caller uses exchangeAuthorizationCode() and passes a scope
  containing openid/email; the client_credentials grant always yields null.

⚠️ One passive behaviour change worth knowing: a consumer that dumps a whole TokenOutput for
debugging (print_r, var_dump, json_encode, or a logger that serializes context objects) will now
see an id_token in that output where nothing appeared before — and an id_token is a JWT carrying PII
(email, sub). No current consumer does this, and it affects only the authorization-code path.

✅ Quality

PHPStan level 8, PHP-CS-Fixer, PHPUnit, and CI verifying PHP 7.1–8.2 compatibility — all clean on this
release branch. Six unit tests added: three on the value object (assignment, the null default, and
one asserting the constructor explicitly does not validate idToken) and three on OAuth2Client
(surfaced from an authorization-code response, left null when absent, left null for
client_credentials). The last two guard the optionality — they fail the day someone makes id_token
required in the shared requestToken(). make verify-71 passes; the new nullable type hint is 7.1
syntax.

📦 Consumers

• Sylius plugin PRE-3631 pins ^1.1.2 — it displays the connected PayPlug account's email on the
  gateway-configuration admin screen, which is impossible on 1.1.0/1.1.1.

📋 Requirements

• PHP ≥7.4 to install/develop (build-tooling floor only — shipped source runs on PHP 7.1)
• Runtime dependency: giggsey/libphonenumber-for-php

🔗 Full Changelog: 1.1.1...1.1.2

1.1.2-rc0

What's Changed

• PRE-3631: expose the OAuth id_token on TokenOutput by @adumont-payplug in #33

Full Changelog: 1.1.1...1.1.2-rc0

1.1.1

🚀 UPC 1.1.1

Corrective release making submerchantExternalId optional across the payment-creation and refund
paths, and adding an optional currency to refunds — non-EUR configurations can now be paid and
refunded, which 1.1.0 made impossible.

🐛 Fixed

• 🏬 submerchantExternalId is no longer required — it belongs to the UDV/MID configuration for
  the payment's currency, not to a payment method: the EUR configurations own a submerchant,
  the ones used for other currencies own none. 1.1.0 required it everywhere, so a non-EUR payment
  or refund was rejected with 400 "Invalid parameter." and had no way through.
  CommonFieldsDto::__construct()'s 5th parameter is now ?string = null, and
  UnifiedApiPaymentService::createRefund()'s 5th is too — both still in place, so existing
  5-argument positional callers are unaffected.
• 🕳️ An empty submerchant is treated as "none" — BuildsCommonPayloadBody and createRefund()
  omit the key entirely when it is null or '', since a CMS reading an unset value out of
  its own settings storage yields '' far more often than a real null, and '' is rejected by
  the API just like a submerchant the configuration does not own. When present, the key keeps its
  original position in the body.

✨ Added

• 💱 currency on refunds — UnifiedApiPaymentService::createRefund() takes an optional
  trailing ?string $currency = null, sent only when non-null and non-empty. Until now no currency
  was sent at all, so $amount's minor units travelled bare for the platform to interpret —
  unambiguous only while every payment used the account's default currency, and a real gap for a
  multi-currency merchant.

♻️ Changed

• createRefund() no longer rejects an empty submerchantExternalId locally with
  InvalidRefundRequestException — orderId and description keep that fail-fast guard.
• BuildsCommonPayloadBody::buildRedirectBody() extracted from buildPayloadBody(); no behavior
  change.
• Design rationale in CLAUDE.md and .env.example corrected in place rather than deleted,
  including the caveat that the staging run which confirmed the fix changed both
  submerchantExternalId and currency at once.

✅ Quality

PHPStan level 8, PHP-CS-Fixer, PHPUnit, and CI verifying PHP 7.1–8.2 compatibility — all clean on
this release branch. Seven unit tests added or reworked around the new omission rules, plus the
refund integration test reworked to run on a configuration that owns no submerchant.

📋 Requirements

• PHP ≥7.4 to install/develop (build-tooling floor only — shipped source runs on PHP 7.1)
• Runtime dependency: giggsey/libphonenumber-for-php

🔗 Full Changelog: 1.1.0...1.2.0

1.1.0

🚀 UPC 1.1.0

Feature release adding card-alias payments (create-and-store, or pay with a saved alias) alongside
the existing hosted-fields flow, plus full/partial refunds against the Unified API.

✨ Added

• 💳 Pay with a saved card alias — new PaymentDto, sibling to HostedFieldDto, for paying
  with an already-created alias (no hfToken). Both share one PaymentRequestPayload contract, so
  UnifiedApiPaymentService::createPayment() accepts either.
• 🏷️ Create an alias from a hosted-fields payment — HostedFieldDto::$recurringMode +
  paymentMethod.saveFutureUsage create an alias for future reuse; PaymentOutput::$aliasId
  surfaces whichever alias was created or reused.
• 🏠 Billing/shipping support — BillingDto/ShippingDto, composing AddressDto/ContactDto/
  ShippingScheduleDto, wired into CommonFieldsDto.
• ↩️ Refunds — UnifiedApiPaymentService::createRefund() for a full or partial refund of a
  payment, validating accountId/orderId/description/submerchantExternalId locally before
  any HTTP call.

💥 Breaking

• UnifiedApiHostedPaymentService is removed; its method now lives directly on
  UnifiedApiPaymentService::createPayment().
• description is now sent unconditionally in every payment-creation request instead of being
  omitted when unset.

✅ Quality

PHPStan level 8, PHP-CS-Fixer, PHPUnit, and CI verifying PHP 7.1–8.2 compatibility — all clean on
this release branch.

📋 Requirements

• PHP ≥7.4 to install/develop (build-tooling floor only — shipped source runs on PHP 7.1)
• Runtime dependency: giggsey/libphonenumber-for-php

🔗 Full Changelog: 1.0.1...1.1.0

1.1.0-rc0

What's Changed

• PRE-3590: Add HF aliasing by @hdelaforce-payplug in #24
• PRE-3589: Fix UPC createRefund() — add required orderId/description/submerchantExternalId fields by @jhoaraupp in #29

New Contributors

• @hdelaforce-payplug made their first contribution in #24

Full Changelog: 1.0.1...1.1.0-rc0

1.0.1

🚀 UPC 1.0.1

Patch release fixing a live notifier incident (PRE-3614) hit while diagnosing production webhook
handling, plus a Unified API operation-status polling fallback developed alongside it.

🐛 Fixes

• 🔁 execCode "0001" no longer misread as a final failure — PayPlug's notifier was
  observed in production firing a webhook carrying execCode "0001" ("Authentification 3DSecure
  requise", categorized "Acceptation", not an error) before the real, final notification for the
  same operation. Under the old two-way mapping this was read as terminal FAILED and, via
  IPaymentRepository::isTreated(), permanently blocked the correct final notification from ever
  applying. ExecCodeMapper::toPaymentOutcome() now maps "0001" to the existing
  PaymentOutcome::THREE_DS_PENDING instead.
• 🔓 Webhook signature verification fails open when no secret is configured —
  WebhookNotificationHelper::verifySignature() previously rejected every notification
  unconditionally, since no merchant/account currently has any way to configure a webhook secret.
  It now accepts the notification unverified when no expected Authorization header value is set.
  This is a deliberate, temporary tradeoff — any unauthenticated request to a plugin's webhook
  endpoint is accepted today — pending a product decision on how webhook secret configuration will
  be exposed; revisit once that lands.

✨ Added

• 📡 Operation-status polling — UnifiedApiPaymentService::getOperation() GETs the public
  /processing-operations/operations/public/{id} endpoint, returning the same webhook-shaped
  payload WebhookNotificationHelper::parse() already reads — a fallback for a delayed or lost
  webhook. A sibling UnifiedApiOperationService::getOperation() targets the private endpoint but
  returns 403 for a merchant's own client credentials in staging; treat it as unverified until a
  follow-up decides whether to keep or remove it.

✅ Quality

PHPStan level 8, PHP-CS-Fixer, PHPUnit, and CI verifying PHP 7.1–8.2 compatibility — all clean on
this release branch.

📋 Requirements

• PHP ≥7.4 to install/develop (build-tooling floor only — shipped source runs on PHP 7.1)
• Runtime dependency: giggsey/libphonenumber-for-php

🔗 Full Changelog: 1.0.0...1.0.1

1.0.1-rc0

What's Changed

• Feature/pre 3614 handling unified notifier by @adumont-payplug in #27

Full Changelog: 1.0.0...1.0.1-rc0

1.0.0

🚀 UPC 1.0.0

This release adds asynchronous webhook/3DS confirmation, synchronous hosted-fields payment
creation, and completes the 3DS-pending redirect flow — the first release with a real end-to-end
payment path, from creation through the bank's 3DS challenge to the final webhook confirmation.

💥 Breaking Changes

No CMS plugin has integrated against UPC yet, so these carry no runtime blast radius today.

• 📦 Models/ → DataValues/ + Output/ — the category is gone; PaymentOutcome/
  OperationData moved to DataValues/ (durable state), Token→TokenOutput,
  AuthorizationRequest→AuthorizationRequestOutput, and the new HostedPaymentResult→
  HostedPaymentOutput moved to Output/ (call-result value objects)
• ✍️ createHostedPayment() signature — replaced its original 11 positional parameters with
  a single validated HostedFieldDto

✨ Highlights

• 🔔 Webhook / 3DS confirmation (PRE-3588) — WebhookNotificationHelper verifies an inbound
  "Payment Operation" notification's Authorization header (constant-time comparison) and parses
  its body into an OperationData, mapping execCode to a PaymentOutcome via the new
  ExecCodeMapper; throws the new InvalidNotificationException on a missing/invalid signature,
  malformed body, or invalid field
• 💳 Hosted-fields payment creation (PRE-3587) — UnifiedApiHostedPaymentService:: createHostedPayment() creates/confirms a payment from an hfToken against the Unified API,
  distinguishing a direct success from a pending 3DS/SCA redirect; new Dto/ (HostedFieldDto,
  CommonFieldsDto, BrowserDto, CustomerDto) and Validators/ (HostedFieldDtoValidator,
  CommonFieldsDtoValidator) categories back the validated input
• 🔁 Completing the 3DS-pending redirect (PRE-3551) — CommonFieldsDto gains successUrl/
  cancelUrl (nested under a redirect object, the merchant-return URLs after the bank's
  challenge); HostedPaymentOutput gains redirectHtml alongside redirectUrl, decoding the
  Unified API's default Base64-encoded redirect.html self-submitting challenge form
• 🏬 Marketplace routing — submerchantExternalId added as a required CommonFieldsDto field

✅ Quality

216 tests / 517 assertions, PHPStan level 8, PHP-CS-Fixer, and CI verifying PHP 7.1–8.2
compatibility — all clean on this release branch.

📋 Requirements

• PHP ≥7.4 to install/develop (build-tooling floor only — shipped source runs on PHP 7.1)
• Runtime dependency: giggsey/libphonenumber-for-php

🔗 Full Changelog: 0.1.0...1.0.0