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

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": "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"
        }
    ]
}

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.

Last updated 9 months ago