Download the PHP package tcgunel/omnipay-odeal without Composer

Omnipay: Ödeal

Ödeal Virtual POS gateway for the Omnipay PHP payment processing library

Omnipay is a framework agnostic, multi-gateway payment processing library for PHP. This package implements the Ödeal (odeal.com) virtual POS API — 3D and non-3D card payments, pay-by-link, cancel (iptal), refund and the transaction query endpoints.

Documentation: docs.odeal.com/sanalpos

How it works

Ödeal authenticates with a short-lived bearer token:

1. POST /token on the token base URL with clientId / clientSecret answers an accessToken (valid ~30 minutes, expiresIn). There is no refresh token flow; issuing a new token invalidates the previous one.
2. Every /vpos operation on the gateway base URL carries Authorization: Bearer {accessToken}.

The gateway fetches the token lazily inside every operation, reuses it for the lifetime of the request and can share it across processes through any PSR-16 cache. When a call still hits a 401 — a concurrent process rotated the token — the token is fetched again and the call replayed once.

Requirements

• PHP 8.3+
• A clientId / clientSecret pair per environment (shared by Ödeal during onboarding)
• For the 3D flow: an endpoint that receives Ödeal's returnUrl callback

Installation

Usage

Gateway initialization

Optional:

Logger (PSR-3, optional)

The package never writes to files or the error log on its own. Inject any PSR-3 logger and the gateway forwards it to every request. Every request/response is logged on debug level, operation outcomes on info/warning and transport problems on error. Credentials and card data are masked before anything reaches the logger:

• clientSecret, bearer tokens and CVVs are replaced with ***
• card numbers keep their BIN and last four digits only (411111******1111)

With Laravel:

Without a logger a Psr\Log\NullLogger is used and nothing is logged.

Shared token cache (PSR-16, optional)

Because issuing a token invalidates the previous one, a shared cache avoids needless token churn when several requests run in parallel. Any PSR-16 cache is accepted; the key is derived from the client id, so several merchants never overwrite each other's token:

The cached token expires tokenCacheSkew seconds (default 30) before Ödeal expires it. A token rejected with 401 is deleted from the cache and replaced.

3D payment (recommended)

purchase() starts the 3D flow by default:

A successful init means the challenge page was issued, not that the payment is complete — that is why isRedirect() is true and isSuccessful() is false while the 3D step is outstanding. Ödeal posts the result to the returnUrl and redirects the browser to successRedirectUrl / failureRedirectUrl afterwards.

Completing / verifying a 3D payment

The callback payload is not signed and may be delayed or lost, so confirm the result against Ödeal by id or externalId (completePurchase() is a check-status call):

checkStatus() does the same; it is exposed separately for reconciliation jobs.

Non-3D (direct) payment

Pay by link

Cancel (iptal — before day-end)

Only the full amount can be cancelled; a partial reversal must be a refund.

Refund (full or partial)

Several partial refunds are allowed as long as their sum does not exceed the original amount.

Transaction details

Credential check

fetchToken() deliberately requests a new bearer token — useful for a "test connection" button. It throws an InvalidResponseException when Ödeal rejects the clientId/clientSecret pair:

Error handling

• Business failures (HTTP 200, result.success = false) come back as a normal response — check isSuccessful() and getMessage().
• Transport problems, non-2xx HTTP statuses and malformed responses throw Omnipay\Common\Exception\InvalidResponseException.
• Missing/invalid request parameters throw Omnipay\Common\Exception\InvalidRequestException (or InvalidCreditCardException for card data) before anything is sent.

Test card / environment

Ödeal shares test credentials and test cards with each merchant; sandbox credentials do not work on production and vice versa.

License

MIT — see LICENSE.