Download the PHP package gopaycommunity/gopay-php-api-v4 without Composer

GoPay PHP SDK — Payments API v4

Server-side PHP SDK for new GoPay Payments API v4.

Requires PHP ≥ 8.1. Transport-agnostic — works with any PSR-18 HTTP client.

v3 → v4 migration

See MIGRATION.md for a full breakdown. The SDK is v4-only — not source-level compatible with gopay/payments-sdk v1.

Key changes:

• Gateway URL changed — update your Config initialization
• Legacy gw_url redirect removed — replace header('Location: gw_url') with chargePayment(). 3DS challenges still redirect via getAction()->getRedirectUrl()
• 10 v3 methods removed — recurrences, pre-auth capture/void, EET, account statement, payment instruments. Refunds are back in v4 on new paths, see Refunds

Installation

For the HTTP client you need a PSR-18 implementation. Guzzle 7 is the most common choice:

Any PSR-18-compatible client works (Symfony HttpClient, Buzz, …).

Quick start

ip, user_agent and accept_header must come from the customer's browser. The browser calls GET /cards/browser-data (authenticated with client_id:shareable_key) immediately before the charge; the response carries all three, and your server merges them into browser_data. The endpoint reports whatever fetched it, so a call from your own server returns the server's address and headers — which the issuer rejects during 3-D Secure. That is why the SDK exposes no method for it: from PHP it would produce exactly the wrong values.

Reading them off the incoming request instead is not the way round it. The Accept headers there do belong to the customer, but ip does not survive a proxy, and the contract wants all three from one observation rather than a mix of two sources.

gw_url — escape hatch for methods not yet on v4. The PaymentDetails object contains a gw_url field. Don't redirect to it by default — this SDK's own flow (createPayment() → chargePayment()) fully covers card payments. Use gw_url deliberately when the payment needs a method or feature not yet implemented in the v4 charge flow: redirecting there hands off real-time control to the hosted (v3-backed) flow while the customer is on it, but the payment remains fully v4-observable — getPaymentStatus() reports the final state once the customer completes it, exactly as it would for a payment charged directly through v4.

Configuration

Environments

PSR-18 HTTP client injection

By default, php-http/discovery auto-discovers an installed PSR-18 client. You can inject your own:

API reference

Authentication

Payments

Cards

Refunds

Server-side only — refundPayment needs the payment:write scope, which a payment-scoped browser token never carries.

A FAILED refund is returned rather than raised — unlike awaitChargeState(), which raises on failure. The refundable amount is untouched, so the caller decides whether to retry.

amount is in minor units and must be positive — the API rejects 0 and negative values with 400.

A card payment can only be refunded in full at first; a partial refund attempted too early is rejected with 409. This is not in the OpenAPI spec — it is the gateway's own rejection, reproduced against the sandbox, which words it as:

Partial refund is not allowed for this payment; only a full refund is possible (e.g. a card payment before settlement can only be fully reversed)

RefundDetails carries id, state, amount, currency, created_at and updated_at. It has no payment_id and no failure reason — the gateway does not return them, so keep your own mapping if you need to resolve a refund back to its payment.

Payment links

A payment link lets you collect a payment without an integration: you create the link, share its url, and the payment is created when the customer opens it. Server-side only — creating and disabling a link need the payment:write scope, reading one needs payment:read.

id and url are two different identifiers and neither can be derived from the other: id is the numeric link ID used by this API, while url ends in a random ten-character code that is the only thing protecting the link.

A reusable link (the default) creates a new payment on every visit — and every one of them carries the same order_number and the same notification_url, so your shop can receive notifications for several payments that all look like one order. Check that it tolerates this before sharing a reusable link.

A one-shot link (reusable => false) is consumed by the first visit and then keeps redirecting to the payment it created, so a customer who refreshes or comes back later still reaches their payment. It cannot be disabled afterwards — disableLink() answers 409, because the link is already inactive. To stop that payment, cancel the payment itself.

Expiry is evaluated on read: once a link is past its expires_at, linkStatus() reports active: false with stop reason EXPIRED without anything being written first.

LinkDetails carries id, url, active, reusable, and — once the link is no longer active — stop_reason (FROM_API, USED or EXPIRED). While the link is active, getStopReason() returns null. A link that belongs to another eshop answers 404, not 403, so the response does not reveal whether it exists.

Response objects

All API methods return typed objects. Use the provided getters to access fields:

Charge flow for 3DS cards

Polling payment state after a redirect

After 3DS the customer is redirected to your return_url. At that point use getPaymentStatus() and PaymentPoller to determine the outcome:

PaymentPoller groups payment states into three buckets:

Post-success states (REFUNDED, PARTIALLY_REFUNDED) are terminal — isTerminal() returns true for them.

QR payment flow

Error handling

All SDK methods throw on error:

Error codes (ErrorCode enum)

onError callback

Production deployment

Token caching

GoPayClient stores the OAuth2 access token in memory inside a single instance. In conventional PHP-FPM / mod_php deployments each HTTP request is a new process, so every new GoPayClient(...) + authenticate() call makes a fresh round-trip to the GoPay token endpoint (typically 50–200 ms).

Tokens are valid for several minutes. To avoid re-fetching on every request, store the raw token in a shared cache (APCu, Redis, Memcached) and restore it before making API calls:

A first-class TokenCacheInterface (injectable into Config) is planned for a future release. Until then, the pattern above or a singleton per worker process is the recommended approach.

awaitChargeState / awaitRefundState in web contexts

awaitChargeState() and awaitRefundState() both usleep() in a loop and block the PHP worker process for up to $timeoutSeconds (default 30 s). Under concurrent load this can exhaust the worker pool. Prefer the webhook-driven pattern for production web servers:

1. GoPay POSTs a notification to your notification_url.
2. Your handler calls getChargeState() — or getRefund() for a refund — once and records the result.
3. Return HTTP 200 immediately.

Use either poller only in CLI scripts or environments with ample worker headroom.

Browser SDK compatibility

The PHP SDK handles the server side; the GoPay browser SDK handles the card form in an iframe.

1. Browser: mountCardForm() → user enters card → iframe submits → returns { token, card_id }.
2. Server: chargePayment($paymentId, ['payment_instrument' => ['payment_instrument' => 'PAYMENT_CARD', 'input' => ['input_type' => 'CARD_TOKEN', 'card_token' => $token]]]).

For browser SDK initialisation, pass the result of getBrowserKeys() to the page:

JWE tokenization flow (return-payload mode)

When the iframe is configured in return-payload mode, it returns a JWE compact serialization string instead of calling /cards/tokens itself. Forward it from the browser to your server, then exchange it for a permanent token:

Examples

Runnable scripts in examples/ demonstrate the full payment flow against the GoPay sandbox. See examples/README.md for setup and usage.

Development

Regenerating model classes

The PHP model classes in src/Generated/ are auto-generated from the GoPay OpenAPI spec. To regenerate them:

This fetches the latest spec from https://api-docs.gopay.com/spec/en/payments.yaml, runs the OpenAPI generator in Docker, and copies the output into src/Generated/. Review the diff before committing — in particular check that the namespace (GoPay\Payments\Generated\Model) and ModelInterface compatibility are preserved.

Do not edit files in src/Generated/ by hand. If a model class is wrong, fix the upstream spec.

License

MIT