# 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ı](https://docs.iyzico.com/on-hazirliklar/sandbox) * [API ve Güvenlik Anahtarı](https://docs.iyzico.com/on-hazirliklar/kimlik-dogrulama) * 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](#a-dim-1-pwi-baslatma) 2. [Token + URL](#a-dim-2-token--url) 3. [Yönlendirme](#a-dim-3-yoenlendirme) 4. [PWI Sorgulama](#a-dim-4-pwi-sorgulama) 5. [Webhook](#a-dim-5-webhook) ### Adım 1 - PWI Başlatma PWI uygulaması, [PWI Başlatma](https://docs.iyzico.com/odeme-metotlari/iyzico-ile-ode/pwi-entegrasyonu/pwi-baslatma) `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;** {% code lineNumbers="true" %} ```json { "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": "email@email.com", "gsmNumber": "+905350000000", "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" } ] } ``` {% endcode %} 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ı;** {% code lineNumbers="true" %} ```json { "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" } ``` {% endcode %} ### 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](https://docs.iyzico.com/odeme-metotlari/iyzico-ile-ode/pwi-entegrasyonu/pwi-baslatma) ve [PWI Sorgulama](https://docs.iyzico.com/odeme-metotlari/iyzico-ile-ode/pwi-entegrasyonu/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 | {% hint style="info" %} mdStatus parametresi sadece 3DS işlemlerinde görünecektir. Lütfen mdStatus ile ilgili daha fazla ayrıntıyı [buradan ](https://beta-deviyzipay.gitbook.io/docs-prod/odeme-metotlari/3ds/3ds-entegrasyonu#mdstatus)kontrol edin. {% endhint %} ### 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;** {% code lineNumbers="true" %} ```json { "locale": "en", //tr "conversationId": "YOUR_CONVERSATION_ID", "token": "YOUR_TOKEN" } ``` {% endcode %} 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ı;** {% code lineNumbers="true" %} ```json { "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" } ``` {% endcode %} ### 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 ismiTipAçıklama
iyziEventTimelongNotification oluşturulma zamanının unix timestamp değeridir.
iyziEventTypestringİstek tipini belirtir. Alabileceği değerler CHECKOUTFORM_AUTH, API_AUTH, THREE_DS_AUTH, BALANCE, BKM_AUTH
iyziReferenceCodestringİstek için üretilen unique iyzico referans kodu
paymentIdlongİlgili ödemenin paymentId bilgisi
paymentConversationIdstringİlgili ödemenin üye işyeri tarafından gönderilmiş referans numarası
statusstringÖ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 ](https://docs.iyzico.com/on-hazirliklar/eslestirme)parametreleri [PWI Sorgulama](https://docs.iyzico.com/odeme-metotlari/iyzico-ile-ode/pwi-entegrasyonu/pwi-sorgulama) yanıtı ve [Webhook](#a-dim-5-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 ](https://docs.iyzico.com/on-hazirliklar/eslestirme)parametreleri de aynı olmalıdır. {% hint style="info" %} 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. {% endhint %}