PWI Örnek Entegrasyon

Bu sayfada, hızlı, kolay ve güvenli uygulama açısından örnek istekler, yanıtlar ve en iyi uygulamaları sunarken, PWI'nin entegrasyon adımlarına kapsamlı bir şekilde daha yakından bakacağız.

Ön Gereksinimler

Devam etmeden önce, lütfen aşağıdaki ön koşullara sahip olduğunuzdan emin olunuz.

• Sandbox Hesabı

• API ve Güvenlik Anahtarı

• API çağrılarını yönetmek için bir yazılım aracı; Postman, Insonmina, Github clients

Genel Bakış

Uygulama, birbiri ardına düzenlenen iki POST isteği gerektirir.

Kısacası;

• İlk olarak, bir PWI Başlatma POST isteğini göstereceğiz.

• Ardından, PWI Sorgulama POST isteği ile tamamlayacağız.

Adımlar

1. PWI Başlatma
2. Token + URL
3. Yönlendirme
4. PWI Sorgulama
5. Webhook

Adım 1 - PWI Başlatma

PWI uygulaması, PWI Başlatma POST isteği ile başlar.

Bu adım, PWI ödemesini başlatmak için bir POST isteği göndermeyi içerir. İstek yapısı; locale, conversationId, price, basketId, paymentGroup, callbackUrl, currency, paidPrice, enabledInstallments, buyer details, shipping address, billing address, and basketItems gibi çeşitli parametreler içerir.

Aşağıdaki örnek bir PWI Başlatma isteği sergilenmiştir.

Örnek PWI Başlatma İsteği;

{
    "locale": "en", //tr
    "conversationId": "conversationID",
    "price": "10.91",
    "basketId": "basketID",
    "paymentGroup": "OTHER",
    "callbackUrl": "YOUR_CALLBACKURL",
    "currency": "TRY",
    "paidPrice": "49.91",
    "enabledInstallments": [
        2,
        3,
        6,
        9,
        12
    ],
    "buyer": {
        "id": "buyerID",
        "name": "buyerName",
        "surname": "buyerSurname",
        "identityNumber": "11111111111",
        "email": "[e-mail]",
        "gsmNumber": "[phone]",
        "registrationAddress": "Burhaniye Mahallesi Atilla Sokak No:7 Üsküdar",
        "city": "Istanbul",
        "country": "Turkey",
        "ip": "85.34.78.112"
    },
    "shippingAddress": {
        "address": "Burhaniye Mahallesi Atilla Sokak No:7 Üsküdar",
        "contactName": "Contact Name",
        "city": "Istanbul",
        "country": "Turkey"
    },
    "billingAddress": {
        "address": "Burhaniye Mahallesi Atilla Sokak No:7 Üsküdar",
        "contactName": "Contact Name",
        "city": "Istanbul",
        "country": "Turkey"
    },
    "basketItems": [
        {
            "id": "ItemID",
            "price": "10.91",
            "name": "product Name",
            "category1": "Category Name",
            "itemType": "PHYSICAL"
        }
    ]
}

Yukarıdaki isteği tetikledikten sonra, çoğunlukla izleyeceğiniz 3 (üç) senaryo vardır. Yanıt payWithIyzicoPageUrl adlı bir değişken içerir.

Örnek PWI Başlatma Yanıtı;

{
    "status": "success",
    "locale": "en", //tr
    "systemTime": 1619779710035,
    "conversationId": "123456789",
    "token": "a641ab63-0b7b-4a50-bb09-6c7325041acd",
    "tokenExpireTime": 1800,
    "payWithIyzicoPageUrl": "https://sandbox-consumer.iyzico.com/checkout?token=a641ab63-0b7b-4a50-bb09-6c7325041acd&lang=tr"
}

Adım 2 - Token + URL

Burada token ve payWithIyzicoPageUrl, ödeme yolculuğunun geri kalanı için temel düğümlerdir.

Bu adımda, önceki adımda aldığınız yanıttan token ve payWithIyzicoPageUrl'yi çıkarmanız gerekir. Token daha sonra doğrulama için kaydedilmelidir ve kullanıcıyı ödeme sayfasına yönlendirmek için payWithIyzicoPageUrl kullanılır.

• token; Satıcıların, ödeme yolculuğunun en sonunda ödemeyle yüzleşmek ve doğrulamak için token parametresini kaydetmesi beklenir.

• payWithIyzicoPageUrl; ödeme sayfasının kısaca göründüğü yer. payWithIyzicoPageUrl'ye yönlendirme, son kullanıcılar için ödeme işlemlerini güvenli bir şekilde gerçekleştirmek için bir arayüz sağlar.

Tarayıcıdaki payWithIyzicoPageUrl Arayüz Örneği;

Adım 3 - Yönlendirme

Yönlendirme aşaması, genel olarak PWI Başlatma ve PWI Sorgulama adımlarını birbirine bağlar.

PWI ödeme sayfasında son kullanıcı etkileşimini takip eden iyzico, sayfayı otomatik olarak "callbackUrl" parametresinde verilen adrese yönlendirecektir. Yönlendirme POST'u şunları içerir;

Input Name	Type	Description
status	String	Servis yanıtı sonucu (başarılı / başarısız)
iyziPaymentId	String	Doğrulama başarılı olursa, iyzico bir ödeme kimliği döndürür. Kimlik doğrulama isteğinde ayarlanmalıdır.
merchantId	String	Satıcı kimliğinizin kimliği.
paymentConversationId	Long	Ayarlanırsa, istek ve yanıtla eşleşecek görüşme kimliği.
token	String	Her ödeme formu isteği için oluşturulan benzersiz değer. Bu belirteç, ödeme sonucuna erişmek için kullanılır.
iyziReferenceCode	String	Bildirim için benzersiz bir referans kodu.
iyziEventType	String	İstek türünü gösterir. Beklenen değer: CHECKOUT_FORM_AUTH

mdStatus parametresi sadece 3DS işlemlerinde görünecektir. Lütfen mdStatus ile ilgili daha fazla ayrıntıyı buradan kontrol edin.

Adım 4 - PWI Sorgulama

PWI Sorgulama, PWI zincirinin son adımıdır.

Temel olarak, bir önceki adımda bir ödemeyi henüz kabul ettik. Şimdi bu adımda işlemi yasallaştırma zamanı. Aşağıdaki örnek, örnek bir PWI Sorgulama istek yapısıdır.

Örnek PWI Sorgulama İsteği;

{
    "locale": "en", //tr
    "conversationId": "YOUR_CONVERSATION_ID",
    "token": "YOUR_TOKEN"
}

Yukarıdaki isteği tetikledikten sonra, çoğunlukla izleyeceğiniz 2 (iki) senaryo vardır. Yanıt PaymentStatus değişkeninde SUCCESS parametresini içerir.

Örnek PWI Sorgulama Yanıtı;

{
    "status": "success",
    "locale": "en", //tr
    "systemTime": 1,
    "conversationId": "YOUR_CONVERSATION_ID",
    "price": 1,
    "paidPrice": 1,
    "installment": 1,
    "paymentId": "GENERIC_PAYMENT_ID",
    "fraudStatus": 1,
    "merchantCommissionRate": 1,
    "merchantCommissionRateAmount": 1,
    "iyziCommissionRateAmount": 1,
    "iyziCommissionFee": 1,
    "binNumber": "000000",
    "lastFourDigits": "0000",
    "basketId": "basketID",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "ItemID",
            "paymentTransactionId": "GENERIC_PAYMENT_TRANSACTION_ID",
            "transactionStatus": 2,
            "price": 1,
            "paidPrice": 1,
            "merchantCommissionRate": 1,
            "merchantCommissionRateAmount": 1,
            "iyziCommissionRateAmount": 1,
            "iyziCommissionFee": 1,
            "blockageRate": 1,
            "blockageRateAmountMerchant": 1,
            "blockageRateAmountSubMerchant": 1,
            "blockageResolvedDate": "GENERIC_DATE",
            "subMerchantPrice": 1,
            "subMerchantPayoutRate": 1,
            "subMerchantPayoutAmount": 1,
            "merchantPayoutAmount": 1,
            "convertedPayout": {
                "paidPrice": 1,
                "iyziCommissionRateAmount": 1,
                "iyziCommissionFee": 1,
                "blockageRateAmountMerchant": 1,
                "blockageRateAmountSubMerchant": 1,
                "subMerchantPayoutAmount": 1,
                "merchantPayoutAmount": 1,
                "iyziConversionRate": 1,
                "iyziConversionRateAmount": 1,
                "currency": "TRY"
            }
        }
    ],
    "phase": "AUTH",
    "token": "YOUR_TOKEN",
    "callbackUrl": "YOUR_CALLBACK_URL",
    "paymentStatus": "SUCCESS"
}

Adım 5 - Webhook

Webhook, uygulama düzenimizin en önemli konusudur.

Gerçek zamanlı ödeme bildirimleri almak, genel PWI deneyiminden yararlanırken, bildirimlerin güvenilir kaynaklardan gelmesini sağlayarak hassas verilere herhangi bir olası kurcalamayı veya yetkisiz erişimi önler.

Her ödeme olayı, webhook tetikler;

• 15 saniye içinde gelir.

• Sunucunuz 200 yanıtı verene kadar devam eder.

• Her 10 dakikada bir tekrarlanır.

• En fazla 3 kez tekrarlanır.

Örnek PWI Webhook

Parametre ismi	Tip	Açıklama
iyziEventTime	long	Notification oluşturulma zamanının unix timestamp değeridir.
iyziEventType	string	İstek tipini belirtir. Alabileceği değerler CHECKOUTFORM_AUTH, API_AUTH, THREE_DS_AUTH, BALANCE, BKM_AUTH
iyziReferenceCode	string	İstek için üretilen unique iyzico referans kodu
paymentId	long	İlgili ödemenin paymentId bilgisi
paymentConversationId	string	İlgili ödemenin üye işyeri tarafından gönderilmiş referans numarası
status	string	Ödeme durumu. Alabileceği değerler: SUCCESS, FAILURE, CALLBACK_THREEDS

Yanıt, status değişkeninde success parametresini içerir.

Onaylama

Ödeme işlemlerinin başarılı bir şekilde sonuçlandırılması için bazı değişkenlerin korelasyonu önemli rol oynar;

• paymentId

• status

• price

• İsteğe bağlı olarak diğer Eşleştirme parametreleri

PWI Sorgulama yanıtı ve Webhook bildirimi birbirini doğrulamalıdır.

PWI Sorgulama'dan alınan yanıtı ve Webhook bildiriminde alınan verileri çapraz doğrulamak çok önemlidir. İşlemin gerçekliğini ve doğruluğunu sağlamak için ödeme paymentId, status, price ve diğer ilgili parametreleri eşleştiriniz.

• PWI Sorgulama yanıtındaki ödeme kimliği, Webhook'tan ödeme kimliğine eşit olmalıdır.

• Her iki status parametresi de success olmalıdır.

• price parametresi tutarları aynı olmalıdır.

• Ve son olarak, Eşleştirme parametreleri de aynı olmalıdır.

Sağlanan örnek isteklerin ve yanıtların yalnızca açıklama amaçlı olduğunu ve bunları kendi özel uygulama gereksinimlerinize ve API belgelerinize uyarlamanız gerektiğini lütfen unutmayın.