@hubcommerce/iyzico

iyzico Checkout Form (iyzico'nun barındırdığı ödeme sayfası), iade/iptal, ödeme sorgu, taksit ve BIN sorgusu için bağımlılıksız istemci. fetch + Web Crypto (IYZWSv2 HMAC-SHA256) — Node ≥20.10 ve Deno / Supabase Edge (npm:) üzerinde aynı kodla çalışır.

Yalnızca sunucu tarafı. secretKey tarayıcıya asla gönderilmemeli.

Resmi iyzipay SDK'sının yerine geçer: callback tabanlı değil, Promise + tipli IyzicoResult<T> döner, çoklu mağaza (tenant) için her mağazaya ayrı client, modül seviyesinde paylaşılan durum yok.

Kurulum

npm install @hubcommerce/iyzico

Deno / Supabase Edge:

import { createIyzicoClient } from "npm:@hubcommerce/[email protected]";

Kullanım

import {
  createIyzicoClient,
  compareCheckoutRetrieve,
  isCheckoutPaymentSuccessful,
  parseCallbackRequest,
} from "@hubcommerce/iyzico";

const iyzico = createIyzicoClient({ apiKey, secretKey, env: "sandbox" }); // veya "production"

// 1) Ödeme formunu başlat
const init = await iyzico.checkoutForm.initialize({
  conversationId: "IYZ7F3K2Q9",          // sizin benzersiz referansınız
  basketId: "ORD-1001",
  price: 150, paidPrice: 150,            // price = sepet satırları toplamı (kuruş kuruş)
  callbackUrl: "https://api.example.com/iyzico/callback",
  enabledInstallments: [1],
  buyer: { id, name, surname, identityNumber: "11111111111", email, registrationAddress, city, country: "Turkey", ip },
  billingAddress: { contactName, city, country: "Turkey", address },
  shippingAddress: { contactName, city, country: "Turkey", address },
  basketItems: [
    { id: "line-1", name: "Tişört", category1: "Giyim", itemType: "PHYSICAL", price: 100 },
    { id: "shipping", name: "Kargo", category1: "Kargo", itemType: "VIRTUAL", price: 50 },
  ],
});
if (!init.ok) throw new Error(init.reason);
// init.data.paymentPageUrl → müşteriyi yönlendirin (veya checkoutFormContent'i gömün)

// 2) Callback: iyzico tarayıcıyı callbackUrl'e POST eder (alan: token) — içerik imzasız, güvenmeyin.
const token = await parseCallbackRequest(request);
const result = await iyzico.checkoutForm.retrieve({ token });
if (result.ok && isCheckoutPaymentSuccessful(result.data)) {
  const mismatches = compareCheckoutRetrieve(result.data, {
    paidPrice: 150, basketId: "ORD-1001", conversationId: "IYZ7F3K2Q9",
  });
  // mismatches boşsa siparişi ödendi işaretleyin (idempotent!)
}

// 3) İade (kısmi tutar destekli) / iptal (aynı gün, tam tutar)
await iyzico.payment.refund({ paymentId, price: 50, ip });
await iyzico.payment.cancel({ paymentId, ip });

// Kimlik bilgisi testi (para hareketi yok)
await iyzico.testConnection();

API özeti

| Metod | Endpoint | Tekrar deneme | |---|---|---| | testConnection() | /payment/bin/check (imzalı) | okuma | | checkoutForm.initialize | /payment/iyzipos/checkoutform/initialize/auth/ecom | yok | | checkoutForm.retrieve | /payment/iyzipos/checkoutform/auth/ecom/detail | okuma | | payment.retrieve | /payment/detail | okuma | | payment.refund | /v2/payment/refund | yok | | payment.refundTransaction | /payment/refund | yok | | payment.cancel | /payment/cancel | yok | | installment.info | /payment/iyzipos/installment | okuma | | installment.checkBin | /payment/bin/check | okuma |

Yardımcılar: formatPrice, toKurus, isCheckoutPaymentSuccessful, isCheckoutPaymentPendingReview, getCheckoutFailureReason, compareCheckoutRetrieve, extractPaymentRefs, parseCallbackRequest, verifyCheckoutForm*Signature, buildAuthorizationHeader.

Ortam

Tek-tenant kullanımda getIyzicoConfigFromEnv() resmi SDK ile aynı env adlarını okur — şablon: .env.example (IYZIPAY_URI, IYZIPAY_API_KEY, IYZIPAY_SECRET_KEY). Yalnızca https://sandbox-api.iyzipay.com ve https://api.iyzipay.com kabul edilir.

Geliştirme

npm run build --workspace=@hubcommerce/iyzico
npm test --workspace=@hubcommerce/iyzico
npm run test:exports --workspace=@hubcommerce/iyzico
npm run test:deno --workspace=@hubcommerce/iyzico      # Deno kurulu ise
npm run qa:smoke --workspace=@hubcommerce/iyzico       # sandbox anahtarlarıyla

Dokümanlar: CONFORMANCE · ADAPTER-CONTRACT · QA · MIGRATION · TECH-DEBT · DOC-SOURCES