Iyzipay Php Laravel Package

Getting Started

Install and confirm the runtime, not just the package.

composer require iyzico/iyzipay-php

There is nothing to publish, no service provider, no config file, no facade. The package is a plain PHP SDK under the Iyzipay\ namespace — every call is a static method on a model class that takes a request object plus a shared Iyzipay\Options instance. Your first job is therefore integration plumbing, not package configuration.

1. Check compatibility before anything else. Look at the installed composer.json for the PHP constraint and confirm the curl extension is present. The SDK is thin over cURL and its releases are infrequent (the project ships roughly annually), so pin the version in composer.json and read the diff before bumping.

2. Read these three files first, in this order, before reading any docs:

   • vendor/iyzico/iyzipay-php/src/Iyzipay/Options.php — what credentials and transport knobs your version actually exposes.
   • One model, e.g. src/Iyzipay/Model/Payment.php and its matching src/Iyzipay/Request/CreatePaymentRequest.php — the static-method shape is identical across the whole SDK.
   • src/Iyzipay/Model/IyzipayResource.php — the base response object, which is where getStatus(), getErrorCode(), getErrorMessage() and getConversationId() come from.

3. Wire credentials into Laravel config, not into code.

// config/services.php
'iyzico' => [
    'api_key'    => env('IYZICO_API_KEY'),
    'secret_key' => env('IYZICO_SECRET_KEY'),
    'base_url'   => env('IYZICO_BASE_URL', 'https://sandbox-api.iyzipay.com'),
    // production: https://api.iyzipay.com
],

4. Bind Options as a singleton in a small IyzicoServiceProvider. This is the single most valuable five lines you will write, because it means no other class in the app ever touches credentials.

$this->app->singleton(\Iyzipay\Options::class, fn () => tap(new \Iyzipay\Options, function ($o) {
    $o->setApiKey(config('services.iyzico.api_key'));
    $o->setSecretKey(config('services.iyzico.secret_key'));
    $o->setBaseUrl(config('services.iyzico.base_url'));
}));

5. First use case: a smoke test command, not a payment. Before you write checkout code, write php artisan iyzico:ping that calls a harmless endpoint — Iyzipay\Model\BinNumber::create() with a known BIN, or Iyzipay\Model\InstallmentInfo::create() for a small price. Both prove credentials, base URL, TLS, and response parsing in one shot. Do this inside tinker first:

$options = app(\Iyzipay\Options::class);
$req = new \Iyzipay\Request\CreateBinNumberRequest;
$req->setLocale(\Iyzipay\Model\Locale::EN);
$req->setConversationId((string) \Str::uuid());
$req->setBinNumber('552879');
$res = \Iyzipay\Model\BinNumber::create($req, $options);
dump($res->getStatus(), $res->getErrorCode(), $res->getErrorMessage());

6. Then build the real first use case: hosted checkout form (CheckoutFormInitialize), not raw card entry. It is the lowest-PCI-scope path, it gets you 3-D Secure for free, and it sidesteps most of the field-validation traps described below. Add Payment/3-D Secure direct integration later, only if you need a fully custom payment page.

Implementation Patterns

Wrap the SDK once behind an interface; never call Iyzipay\Model\* from a controller. Static methods are effectively untestable, so the wrapper is what makes the rest of your app testable.

interface PaymentGateway {
    public function startHostedCheckout(Order $order): string;      // returns redirect URL
    public function completeHostedCheckout(string $token): PaymentResult;
    public function authorize3ds(Order $order, CardForm $card): string; // returns HTML
    public function complete3ds(array $callback): PaymentResult;
    public function refund(Order $order, int $amountMinor, string $ip): PaymentResult;
    public function cancel(Order $order, string $ip): PaymentResult;
    public function installments(string $bin, int $amountMinor): array;
}

Hosted checkout (recommended default).

$req = new \Iyzipay\Request\CreateCheckoutFormInitializeRequest;
$req->setLocale(\Iyzipay\Model\Locale::EN);
$req->setConversationId($order->uuid);              // your idempotency handle
$req->setCallbackUrl(route('iyzico.callback'));
$req->setPrice($this->money($order->total_minor));
$req->setPaidPrice($this->money($order->total_minor));
$req->setCurrency(\Iyzipay\Model\Currency::TL);
$req->setBasketId($order->uuid);
$req->setPaymentGroup(\Iyzipay\Model\PaymentGroup::PRODUCT);
$req->setEnabledInstallments([1, 2, 3, 6, 9]);
$req->setBuyer($this->buyer($order));
$req->setShippingAddress($this->address($order));
$req->setBillingAddress($this->address($order));
$req->setBasketItems($this->items($order));

$init = \Iyzipay\Model\CheckoutFormInitialize::create($req, $options);
// persist $init->getToken() against the order, then redirect
return redirect()->away($init->getPaymentPageUrl());

On the callback route, token arrives as a query parameter; call CheckoutForm::retrieve() with a RetrieveCheckoutFormRequest carrying that token. getPaymentStatus() on the retrieved form is the source of truth — not the status field, not the HTTP code.

Direct 3-D Secure (ThreedsInitialize → ACS → ThreedsPayment). Use this only when you must own the card form. ThreedsInitialize::create() returns HTML (getHtmlContent()) that is an auto-submitting form. Return it raw from a dedicated route, never through a Blade layout, and have the bank redirect back to a CSRF-exempt POST route. There you rebuild the call:

$req = new \Iyzipay\Request\CreateThreedsPaymentRequest;
$req->setLocale(\Iyzipay\Model\Locale::EN);
$req->setConversationId($callback['conversationId']);
$req->setPaymentId($callback['paymentId']);
$req->setConversationData($callback['conversationData']);
$res = \Iyzipay\Model\ThreedsPayment::create($req, $options);

Treat mdStatus == 1 as fully authenticated; anything else is a failed or attempted authentication and must not be fulfilled.

Model the payment as a state machine with an audit table. One row per attempt: conversation_id (unique index), order_id, kind (hosted/3ds/direct), request_payload, response_payload, status, payment_id, payment_transaction_id, error_code. iyzico does not push webhooks for one-off payments — your only durable record of what happened is what you saved at callback time. This table is also your chargeback defence file.

Idempotency by conversationId. Generate it yourself (order UUID or order-{attempt}), store it before the call, and on any retry look it up first. Both the hosted and 3-D Secure callbacks can be replayed by the browser or the bank; dedupe on conversationId + paymentId before creating a second payment record.

Money handling. Store minor units (bigint kuruş) in the database and convert at the boundary:

private function money(int $minor): string {
    return number_format($minor / 100, 2, '.', ''); // "1234.50", never a float
}

Refunds are per line item, not per order. Capture paymentTransactionId for each getPaymentItems() entry at success time and persist it against the order line. Then:

$req = new \Iyzipay\Request\CreateRefundRequest;
$req->setPaymentTransactionId($line->iyzico_transaction_id);
$req->setPrice($this->money($amountMinor));
$req->setCurrency(\Iyzipay\Model\Currency::TL);
$req->setIp(request()->ip());

Cancel (same-day, full amount only) uses paymentId instead. Decide from your order state which one applies; many teams wrongly call Refund on unsettled same-day payments and get unexplained failures.

Installment table UX. InstallmentInfo::create() with BIN + price returns per-bank installment options with installmentNumber, installmentPrice, totalPrice. Cache the result for a few minutes keyed by BIN; call it on BIN blur, not on every keystroke.

Saved cards. Send setRegisterCard(1) with a stable cardUserKey (hash of your customer id is fine) and persist the cardUserKey/cardToken returned on the payment. CardList::retrieve() then feeds a "saved cards" UI. Requires merchant-level approval from iyzico — do not build the UI until it is enabled.

Queue anything that can be slow and everything that must not be lost. Wrap the callback handling in a job that is safe to re-run; wrap refunds in jobs with a uniqueId. Sync calls in a request are fine at low volume but the SDK has no timeout knob you can rely on in every version, so a slow iyzico response becomes a hung PHP worker.

Test with a fake, not with the sandbox. Bind a FakePaymentGateway implementing your interface in TestCase. Keep exactly one sandbox integration test, marked @group external, that runs against the sandbox base URL in CI-nightly.

Gotchas and Tips

HTTP 200 does not mean success. iyzico returns a normal response body for failures. Every single call must branch on $res->getStatus() === 'success' and on getPaymentStatus() where applicable. A controller that does if ($res) { markPaid(); } is the classic production incident in this SDK.

Failures arrive as values, not exceptions — but not always. Network/curl errors sometimes surface as an exception, sometimes as a failure-status object with a transport error code. Wrap every SDK call in try/catch (\Throwable) and check status. Never assume getPaymentId() on a failed response is null-safe across versions.

Amounts must be strings, and they must reconcile. setPrice() as a float produces 10.0 vs 10.00 mismatches. More painfully, the sum of basket item prices must equal price exactly, and paidPrice must be >= price (equal when installment = 1, greater when you pass the installment difference to the cardholder). A one-kuruş mismatch is rejected with a validation error that reads like a generic failure.

Currency::TL is the constant you want, and its wire value is TRY. Don't invent 'TRY' strings and don't assume Currency::TRY exists. Also, cross-currency refunds fail — the refund currency must match the payment's.

Turkish error messages by default. Set setLocale(\Iyzipay\Model\Locale::EN) on every request if your logs and support staff are English-speaking. Keep the original Turkish errorMessage in your audit row regardless; it is what iyzico support will ask for.

Buyer fields are mandatory and validated. identityNumber is required and, for Turkish citizens, checksum-validated — a placeholder will fail intermittently. For foreign buyers use the passport number or the documented fallback, and make it a per-order field, not a hardcoded constant. Same for ip, city, country, registrationAddress, gsmNumber: build one buyer() mapper and unit-test it.

Callbacks are cross-site and unauthenticated. The 3-D Secure callback and the hosted-form return are POSTs from the bank/iyzico: add them to VerifyCsrfToken::$except, do not require auth, and never trust the payload until CheckoutForm::retrieve() or the ThreedsPayment response confirms it server-side. Also assume session state is gone — a returning user may be on a different device or a new PHP session.

Rendering getHtmlContent(). It is a complete self-submitting HTML document. Echo it raw, return it with a text/html response, and relax form-action in CSP for the ACS domains. Never pass it through Blade's escaped {{ }}.

Refunds need transaction ids and merchant balance. paymentTransactionId comes from payment items, not from the payment. Refunds fail when the merchant's iyzico balance can't cover them — that's a real error to surface to ops, not a bug to retry blindly. Partial refunds must not exceed the line's remaining refundable amount; enforce that in your own code because the API will not.

No idempotency key on the wire. conversationId is echoed back but does not prevent duplicate charges. Your DB unique index and a "pending attempt" lookup are the only real dedupe.

Not a Laravel package. No config merge, no facade, no events, no HTTP client abstraction, no retries, no logging hooks. If you need timeouts or a proxy, check Options.php in your installed version — if the knob isn't there, don't patch vendor; run the call inside a queued job with a supervisor timeout instead.

Testing friction is the price of static methods. Because every entry point is SomeModel::create($request, $options), you cannot mock the SDK. Define your own interface (as above), bind a fake in tests, and keep the SDK calls in exactly one adapter class so the untestable surface stays at one file.

Upgrade discipline. Releases are infrequent and the changelog is thin; read the src/Iyzipay/Request diffs before bumping, since request-class setter signatures (especially the subscription and card-storage models) change without much ceremony. Run the sandbox integration test after every bump.