Sipariş Oluşturma - Shop API Docs

Bu sayfada yer alan bilgiler, sepetin son adımındaki ödeme ve sipariş oluşturma işlemlerini açıklamaktadır.

Ödeme işlemi 3D'li kredi kartı ödeme işlemlerinde 2 adımlı, 3D'siz ve kapıda ödeme, havale vs. gibi işlemlerde tek adımlıdır. Bunun sebebi ise 3D'li işlemlerde banka doğrulaması için bir HTML içeriği dönülmesi ve bu şekilde bankanın arayüzüne SMS doğrulaması için redirect yapılmasıdır. SMS doğrulamasından sonra ise tekrar sepete dönülür ve Ödeme işlemini tamamlama servisi çağırılarak, ödeme işlemi tamamlanır.

Tek adımlı ödemeler (Kapıda ödeme, havale & eft vb.) bu yönlendirme işlemi olmayacağından, Ödeme işlemini tamamlama servisinin çağırılmasına gerek yoktur. Ödeme isteği oluşturma servisinden dönen response success ise sipariş oluşturulur.

Ödeme İsteği Oluşturma

post

/api/shop/checkout

Bu serviste bir ödeme isteği oluşturarak, siparişi tamamlamak için gerekli adımları başlatabilirsiniz.

Bu servise istek gönderirken kullanıcı doğrulaması yapılması zorunludur. Login servisinden alınan token bilgisi header içerisinde Bearer Token olarak gönderilmelidir.

Parametre Tanımlamaları

Değerler	Zorunluluk	Ön Tanımlı	Açıklama
callbackUrl	evet		Kredi Kartı 3D'li işlemler için verilecek callback URL
basketId	evet		Siparişin oluşturulabilmesi için daha önce oluşturulan benzersiz sepet kimliği
checkoutId	evet		Ödeme işlemi ile ilişkilendirilmesi için daha önce oluşturulan benzersiz ödeme kimliği
billingAddressId	evet		Seçilen fatura adresi
shippingAddressId	evet		Seçilen teslimat adresi
paymentMethod	evet		Seçilen ödeme yöntemi
paymentGateway	evet		ödeme yöntemine ait ödeme seçeneklerini listeleme servisinden alınan ödeme sağlayıcı kodu
deliveryOption	hayır		Seçilen teslimat yöntemi. Teslimat seçenekleri listeleme servisindeki seçilen servis sağlayıcıya ait datayı içermelidir.
creditCardForm	hayır		Kredi kartı ile ödeme ise bu alanın doldurulması gerekmektedir.
creditCardForm->cardName	hayır		Kart üzerindeki isim
creditCardForm->cardNumber	hayır		Kart numarası
creditCardForm->cardMonth	hayır		Son kullanma tarihi ay bilgisi. Çift haneli olacak şekilde yazılmalıdır.
creditCardForm->cardYear	hayır		Son kullanma tarihi yıl bilgisi. 4 haneli olacak şekilde yazılmalıdır.
creditCardForm->cardCvv	hayır		Kartın arka yüzündeki CVV kodu, genelde 3 haneli, maks 4 hanelidir.
creditCardForm->registerCard	hayır		Kart kayıt edilsin mi? kart kayıt edilirse, token ile ödeme alınabilir.
creditCardForm->installment	hayır		Taksit bilgisi. Tek çekim ise 1 gönderilmelidir.
creditCardForm->cardToken	hayır		Kayıtlı kart ile demean yapılırsa kart token bilgisi gönderilmesi yeterlidir.
lang	hayır	tr	Servisten beklenen dil bilgisidir. Merchant'a tanımlı dil bilgileri ile istek yapılabilir.
countryCode	hayır	TR	Ülke bilgisidir

Örnek İstek

axios.post('{baseUrl}/api/shop/checkout', {
    "billingAddressId": "629f3fb9e76c0ce169001ba2",
    "shippingAddressId": "629f3fb9e76c0ce169001ba2",
    "paymentMethod": "creditCard",
    "paymentGateway": "iyzico",
    "deliveryOption": {
        "providerName": "MNG Kargo",
        "providerCode": "MNG",
        "providerLogo": "https://app.labsoffice.com/images/cargo/mng.svg",
        "isRefundable": false,
        "isPaymentable": true,
        "isPrimary": true,
        "estimatedDays": "1-3",
        "country": "TR",
        "price": {
            "currency": "₺",
            "value": 19.90,
            "indoor": 9.90
        }
    },
    "creditCardForm": {
        "installment": "1",
        "cardName": "John Doe",
        "cardNumber": "5890040000000016",
        "cardMonth": "12",
        "cardYear": "24",
        "cardCvv": "123"
    },
    "basketId" : "8117ebbe-2d0d-4132-88ef-6768e3b5d084",
    "checkoutId" : "1fda092d-a37a-4c85-ad3e-ae610e2cca02",
    "callbackUrl" : "https://example-store.com/api/payment-callback"
})

Servis Cevabı ve Alan Açıklamaları

Alan adı	Açıklama
status	İşlem sonucu (success, error)
message	İşlem sonucu açıklaması
htmlContent	Eğer 3D işlem ise, bankanın güvenlik doğrulaması için yönlendirme yapılacak html kodlarını içerir.
orderId	3D'li işlem değilse, oluşturulan sipariş ait referans numarası

{
  "status": "success",
  "message": "İşlem başarılı",
  "htmlContent": "<!doctype html>\n<html lang=\"en\">\n<head>\n    <title>iyzico Mock 3D-Secure Processing Page</title>\n</head>\n<body>\n<form id=\"iyzico-3ds-form\" action=\"https://sandbox-api.iyzipay.com/payment/mock/init3ds\" method=\"post\">\n    <input type=\"hidden\" name=\"orderId\" value=\"mock46-2922326973513399iyziord\">\n    <input type=\"hidden\" name=\"bin\" value=\"552608\">\n    <input type=\"hidden\" name=\"successUrl\" value=\"https://sandbox-api.iyzipay.com/payment/iyzipos/callback3ds/success/27\">\n    <input type=\"hidden\" name=\"failureUrl\" value=\"https://sandbox-api.iyzipay.com/payment/iyzipos/callback3ds/failure/27\">\n    <input type=\"hidden\" name=\"confirmationUrl\" value=\"https://sandbox-api.iyzipay.com/payment/mock/confirm3ds\">\n    <input type=\"hidden\" name=\"PaReq\" value=\"d964640a-8f92-4802-bfa0-4b6fbbeeb533\">\n</form>\n<script type=\"text/javascript\">\n    document.getElementById(\"iyzico-3ds-form\").submit();\n</script>\n</body>\n</html>"
}

Ödeme işlemine dair sonuç aldıktan sonra 2 senaryo mevcuttur. Birinci senaryo, 3D'siz kredi kartı ödemeleri, kapıda ödeme yada havale ile ödeme seçeneklerinde geçerli olan status : 'success' alınan ve htmlContent alanını içermeyen sonuçlar için geçerli olan senaryodur. Bu senaryoda işlem direkt onaylanır ve sipariş oluşturulur. htmlContent yerine orderId bilgisi döner ve "Sipariş oluşturma başarılı" sayfasına yönlendirme yapılması beklenir.

3D ile ödeme gibi ikinci senaryolarda ise, banka sayfasına yönlendirme yaparak güvenlik doğrulaması adımı işlenmesi gerektiğinden dolayı servisten htmlContent alanı döner ve bankaya aşağıdaki şekilde html içeriği replace edilerek yönlendirme yapılır.

document.open();
document.write(response.data.htmlContent);
document.close();

Bu adımda, kullanıcının karşısında bankaya ait SMS doğrulaması ekranı çıkar ve kullanıcı doğrulama adımını tamamladıktan sonra ilk istekte verilen callbackUrl adresine yönlendirilir. Bu işlem sırasında hala müşterinin kartından para çekilmemiştir. Sadece bankadan para çekme işlemi için onay alınmıştır. Para çekme işlemini tamamlamak için son adım olan "Ödeme isteğini tamamlama" servisi çalıştırılır.

Özetle; banka müşteri doğrulamasından sonra verilen callbackUrl adresine bir data iletir ve bizim bu datayı callbackUrl'de alarak son adımı çalıştırmamız beklenir.

Ödeme İsteğini Tamamlama

post

/api/shop/checkout-complete

Bu serviste bankadan dönen ödeme işlemine ait veriler ile birlikte müşterinin kredi kartından ilgili tutarı çekerek siparişi tamamlayabilirsiniz.

Parametre Tanımlamaları

Değerler	Zorunluluk	Ön Tanımlı	Açıklama
basketId	evet		Siparişin oluşturulabilmesi için daha önce oluşturulan benzersiz sepet kimliği
checkoutId	evet		Ödeme işlemi ile ilişkilendirilmesi için daha önce oluşturulan benzersiz ödeme kimliği
payload	evet	TR	Bankadan dönen ödeme onayına ait veri kümesidir. Her bir ödeme sağlayıcıda farklı veri dönebilir.
lang	hayır	tr	Servisten beklenen dil bilgisidir. Merchant'a tanımlı dil bilgileri ile istek yapılabilir.

Örnek İstek

axios.post('{baseUrl}/api/shop/checkout-complete', {
    "payload": {
        ...request.body // callback url'e gönderilen post datasını olduğunu gibi buraya ekliyoruz
    },
    "basketId" : "8117ebbe-2d0d-4132-88ef-6768e3b5d084",
    "checkoutId" : "1fda092d-a37a-4c85-ad3e-ae610e2cca02",
    "lang" : "tr"
})

Servis Cevabı ve Alan Açıklamaları

Alan adı	Açıklama
status	İşlem sonucu (success, error)
message	İşlem sonucu açıklaması
orderId	Oluşturulan sipariş ait referans numarası
basketId	Sepet kimliği
checkoutId	Ödeme kimliği
paymentMethod	Sipariş ödeme yöntemi : creditCard, indoorPayment, indoorPaymentWithPos, bankTransfer

{
  "status": "success",
  "message": "Sipariş oluşturma işlemi başarılı!",
  "orderId": 167522,
  "basketId": "8117ebbe-2d0d-4132-88ef-6768e3b5d084",
  "checkoutId": "1fda092d-a37a-4c85-ad3e-ae610e2cca02",
  "paymentMethod": "creditCard",
}

Önemli Not: Bu aşamadan sonra sipariş oluştuğundan dolayı, sonraki işlemlerde çakışma yada hata ile karşılaşmamak adına checkoutId ve basketId yeniden üretilmeli ve eski değerleri varsa önbellekten silinmelidir.