Download the PHP package onpayio/php-sdk without Composer

OnPay PHP SDK

PHP SDK for the OnPay payment platform.

• API reference: https://onpay.io/docs/technical/api_v1.html
• Payment window reference: https://onpay.io/docs/technical/paymentwindow_v3.html
• Upgrading from 1.x: UPGRADE.md

Requirements

• PHP 8.2 or later.
• A PSR-18 HTTP client with PSR-17 factories, for example Guzzle. The SDK does not ship one. A common client such as Guzzle or Symfony's is discovered automatically; anything else you pass to the constructor (see Using your own HTTP client).

Installation

Replace guzzlehttp/guzzle with the PSR-18 client you use. Composer may ask whether to allow the php-http/discovery plugin; either answer works, discovery needs no plugin at runtime.

Getting started

1. Store the access token

The SDK hands you the OAuth token as a string and asks for it back on every request. Implement OnPay\TokenStorageInterface to keep it somewhere durable and private: the token gives full API access, so treat it like a database password.

2. Store the authorization state

The OAuth flow spans two requests: one that redirects the merchant to OnPay and one that receives the authorization code. Implement OnPay\AuthStateStorageInterface to carry the CSRF state and PKCE verifier between them, scoped to the current visitor. A PHP session is the simplest place:

3. Authorize

After that the token is refreshed and re-saved automatically. isAuthorized() makes a ping request to check that the stored token still works.

A static API token created in the OnPay management panel skips the flow entirely:

4. Create a payment

Describe the payment with a PaymentWindow, create it through the API and send the shopper to the returned payment window link. Amounts are in minor units.

Every field the API accepts has a setter on PaymentWindow and PaymentInfo; the API reference describes them. Some payment methods need a cart. Its total, items plus shipping and handling minus discount, must equal the payment amount:

To store the card for later charges, create a subscription (see Stored cards) instead of a one-off payment. It should charge its first transaction as part of the signup, so the shopper authenticates the real amount and liability shifts to the issuer. Create one without a transaction only for a trial period or when replacing a stored card.

5. Verify the result

OnPay signs the onpay_* parameters it appends to the accept URL and sends to the callback URL (a GET request). Check the signature with your payment window secret before trusting them. Declines sent to the decline URL are not signed.

Transactions

Stored cards (COF)

OnPay stores a card as a subscription, the card on file (COF) of the card-scheme rules, and that is the name the API and these methods use. Charging it later, without the shopper present, is a merchant-initiated transaction (MIT).

Gateway

Configuration-time lookups. Cache the results; do not call these while processing a payment.

Errors

Every error the SDK raises extends OnPay\API\Exception\OnPayException:

Invalid constructor options throw a plain \InvalidArgumentException.

Logging

Failed requests are logged at warning (4xx) or error (5xx, transport failure), successful ones at debug. Tokens and secrets are redacted first. Pass any PSR-3 logger; without one, warnings and errors go to PHP's error_log().

Pass a Psr\Log\NullLogger to silence the SDK.

Using your own HTTP client

Any PSR-18 client works. When you inject one, timeouts, proxies and TLS settings are whatever you configured on it. When the SDK discovers Guzzle itself it creates the client with a 30-second timeout and a 5-second connect timeout; any other discovered client runs with its own defaults.

Factories you leave out are discovered from the installed packages.

Payment window as an HTML form

The payment window can also be opened by posting a signed form directly from the browser, without an API call. It needs the gateway id and payment window secret from the OnPay management panel, plus an accept URL. Prefer creating the payment through the API when you can.

The result is verified exactly as in Verify the result.