Entegrasyon

JS SDK ve kart formu

Müşteriyi başka bir sekmeye göndermeden, kendi sayfanızda gömülü bir ödeme formu gösterin. Kart bilgisi yine mağazanıza uğramaz: form, korumalı bir iframe içinde pay.paymentgateway.com.tr'de çalışır.

Bu, hazır ödeme sayfasının bir varyantıdır

Aynı oturum ve ödeme altyapısını kullanır (bkz. hazır ödeme sayfası); tek fark, tam sayfa yönlendirme yerine sayfanıza gömülü bir <iframe>'de açılmasıdır. 3D Secure adımı da aynı iframe içinde tamamlanır.

Akış

Sunucunuz POST /v1/checkout/sessions ile "embed": true ve returnUrl vererek bir oturum oluşturur. returnUrl'ün kökeni (ör. https://magaza.com), formun hangi siteye gömülmesine izin verileceğini belirler — başka hiçbir site bu oturumu gömemez.
Sayfanıza pgw.js'i ekleyip PGW.embed(...) çağırırsınız; SDK oturum adresini bir iframe'e yükler ve yüksekliğini içeriğe göre otomatik ayarlar.
Müşteri kart bilgisini iframe içinde girer; gerekiyorsa 3D Secure de aynı iframe içinde tamamlanır.
Sonuç, sayfanıza postMessage ile bildirilir; onSuccess/onDeclined/onPending geri çağrılarınız tetiklenir.

1. Gömülü oturum oluşturun

POST/v1/checkout/sessions

curl https://api.paymentgateway.com.tr/v1/checkout/sessions \
  -H "Authorization: Bearer pgw_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "TRY",
    "merchantOrderId": "1002",
    "returnUrl": "https://magaza.example",
    "embed": true,
    "maxInstallment": 6
  }'

Alan	Açıklama
`embed`	true: form iframe içinde açılmaya uygun hale gelir (postMessage ile sonuçlanır, tam sayfa yönlendirme yapılmaz).
`returnUrl`	embed:true iken zorunludur; yalnızca kökeni (origin) kullanılır ve o kökenden gömülmesine izin verilir (Content-Security-Policy: frame-ancestors).

2. pgw.js'i ekleyin

Sayfanıza

<div id="pgw-form"></div>
<script src="https://pay.paymentgateway.com.tr/pgw.js"></script>
<script>
  PGW.embed({
    url: session.url, // 1. adımda sunucunuzdan aldığınız oturum adresi
    container: "#pgw-form",
    onSuccess: function (result) {
      // result: { status: "captured" | "authorized", paymentId, orderId }
      window.location.href = "/siparis/" + result.orderId + "/tesekkurler";
    },
    onPending: function (result) {
      // Sonuç sağlayıcıdan doğrulanıyor (ör. bazı yöntemlerde birkaç saniye sürebilir).
      // Kesin durumu webhook veya GET /v1/payments/{id} ile öğrenin.
    },
    onDeclined: function (result) {
      // result.error: kullanıcıya gösterilebilir mesaj. Form aynı iframe içinde açık kalır, müşteri
      // başka bir kartla tekrar deneyebilir.
    },
  });
</script>

Seçenek	Açıklama
`url`	1. adımdaki oturumun url alanı (zorunlu).
`container`	CSS seçici (string) ya da DOM elemanı (zorunlu).
`minHeight`	İçerik yüklenene kadarki başlangıç yüksekliği, piksel (varsayılan 420).
`onSuccess / onPending / onDeclined`	Sonuç geri çağrıları; hepsi tek bir obje alır.

Sonucu her zaman sunucu tarafında doğrulayın

onSuccess tarayıcı tarafında çalışır ve manipüle edilebilir; siparişi kesinleştirmeden önce webhook ile veya GET /v1/payments/{id} ile durumu sunucunuzda doğrulayın. onSuccess'u yalnızca kullanıcı arayüzünü güncellemek (ör. yönlendirme) için kullanın.

Görünüm

Iframe genişliği container'ınıza uyar (width: 100%) ve yüksekliği içeriğe göre otomatik değişir; ekstra bir stil ayarlamanız gerekmez. Formun kendi görünümü (renk, yazı tipi) şu an sabittir; markanıza göre özelleştirme yol haritamızdadır.

← ÖncekiHatalar ve durumlar Sonraki →E-ticaret eklentileri