# CF Örnek Entegrasyon

Bu dokümanda, [Redirect Form](https://beta-deviyzipay.gitbook.io/docs-prod/odeme-metotlari/odeme-formu/cf-entegrasyonu#redirect) ile [CF](https://docs.iyzico.com/odeme-metotlari/odeme-formu)'nin kapsamlı entegrasyon adımlarını derinlemesine inceleyeceğiz ve hızlı, kolay ve güvenli bir entegrasyon için örnek istekler, yanıtlar ve en iyi uygulamalar sağlayacağı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ış

[CF](https://docs.iyzico.com/odeme-metotlari/odeme-formu)'nin uygulanması, birbirini izleyen iki `POST` isteğinin birbiri ardına düzenlenmesini gerektirir.

 Kısacası; 

* İlk olarak, bir **CF Başlatma** `POST` isteğini göstereceğiz.
* Ardından, **CF Sorgulama** `POST` isteği ile tamamlayacağız.

### Adımlar

1. [CF Başlatma](#a-dim-1-cf-baslatma)
2. [Token + URL](#a-dim-2-token--url)
3. [Yönlendirme](#a-dim-3-yoenlendirme)
4. [CF Sorgulama](#a-dim-4-cf-sorgulama)
5. [Webhook](#a-dim-5-webhook)

### Adım 1 - CF Başlatma

CF uygulaması, [CF Başlatma](https://docs.iyzico.com/odeme-metotlari/odeme-formu/cf-entegrasyonu/cf-baslatma) `POST` isteği ile başlar.

Bu adım, bir `POST` isteği göndermeyi içerir ve istek yapısı; locale, conversationId, price, basketId, paymentGroup, callbackUrl, currency, paidPrice, enabledInstallments, buyer details, shipping address, billing address ve basketItems gibi çeşitli parametreler içerir.

Aşağıdaki nesne, örnek bir [CF Başlatma](https://docs.iyzico.com/odeme-metotlari/odeme-formu/cf-entegrasyonu/cf-baslatma) istek gövdesidir.

#### **Örnek CF Başlatma İsteği;**

{% code lineNumbers="true" %}

```json
{
   "locale":"en",
   "conversationId":"sampleConversationId",
   "price":"5.2",
   "basketId":"B67832",
   "paymentGroup":"PRODUCT",
   "buyer":{
      "id":"BY789",
      "name":"Higher",
      "surname":"Faster",
      "identityNumber":"74300864791",
      "email":"stronger@implementation.com",
      "gsmNumber":"+905555434332",
      "registrationAddress":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
      "city":"Istanbul",
      "country":"Turkey",
      "ip":"85.34.78.112"
   },
   "shippingAddress":{
      "address":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
      "contactName":"Jane Doe",
      "city":"Istanbul",
      "country":"Turkey"
   },
   "billingAddress":{
      "address":"Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
      "contactName":"Jane Doe",
      "city":"Istanbul",
      "country":"Turkey"
   },
   "basketItems":[
      {
         "id":"BI101",
         "price":"5.2",
         "name":"Binocular",
         "category1":"Category 1",
         "itemType":"PHYSICAL"
      }
   ],
   "callbackUrl":"YOUR_CALLBACKURL",
   "currency":"TRY",
   "paidPrice":"5.2",
   "paymentSource":"zooz",
   "enabledInstallments":[
       2,3
   ]
}
```

{% endcode %}

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

**Örnek CF Başlatma Yanıtı;**

{% code overflow="wrap" lineNumbers="true" %}

```json
{
    "status": "success",
    "locale": "en",
    "systemTime": 1687112732811,
    "conversationId": "sampleConversationId",
    "token": "a5b67652-c24a-4347-b61e-6c957bf30f1b",
    "checkoutFormContent": "<script type=\"text/javascript\">if (typeof iyziInit == 'undefined') {var iyziInit = {currency:\"TRY\",token:\"a5b67652-c24a-4347-b61e-6c957bf30f1b\",price:5.20,locale:\"en\",baseUrl:\"https://sandbox-api.iyzipay.com\", merchantGatewayBaseUrl:\"https://sandbox-merchantgw.iyzipay.com\", registerCardEnabled:true,bkmEnabled:true,bankTransferEnabled:true,bankTransferTimeLimit:{\"value\":5,\"type\":\"day\"},bankTransferRedirectUrl:\"YOUR_CALLBACKURL\",bankTransferCustomUIProps:{},campaignEnabled:false,campaignMarketingUiDisplay:null,paymentSourceName:\"zooz\",plusInstallmentResponseList:null,payWithIyzicoSingleTab:true,payWithIyzicoOneTab:false,mixPaymentEnabled:true,creditCardEnabled:true,bankTransferAccounts:[{\"iban\":\"TR020006200035600006294884\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"Garanti Bankası\",\"bankId\":62,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/62.svg\"},{\"iban\":\"TR080006400000111351092786\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"İş Bankası\",\"bankId\":64,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/64.svg\"},{\"iban\":\"TR340004600786888000080896\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"Akbank\",\"bankId\":46,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/46.svg\"},{\"iban\":\"TR910006701000000096073759\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"Yapı Kredi Bankası\",\"bankId\":67,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/67.svg\"},{\"iban\":\"TR760001001187768823545001\",\"legalCompanyTitle\":\"iyzi Ödeme ve Elektronik Para Hizmetleri A.Ş.\",\"currency\":\"TRY\",\"bank\":\"Ziraat Bankası\",\"bankId\":10,\"bankLogoUrl\":\"https://static.iyzipay.com/checkoutform/img/banks/10.svg\"}],userCards:[],fundEnabled:true,memberCheckoutOtpData:{},force3Ds:false,isSandbox:true,storeNewCardEnabled:true,paymentWithNewCardEnabled:true,enabledApmTypes:[\"SOFORT\",\"IDEAL\",\"QIWI\",\"GIROPAY\"],payWithIyzicoUsed:false,payWithIyzicoEnabled:true,payWithIyzicoCustomUI:{},buyerName:\"Higher\",buyerSurname:\"Faster\",merchantInfo:\"\",merchantName:\"Sandbox Merchant Name - 3389550\",cancelUrl:\"\",buyerProtectionEnabled:false,hide3DS:false,gsmNumber:\"+905555434332\",email:\"stronger@implementation.com\",checkConsumerDetail:{},subscriptionPaymentEnabled:false,ucsEnabled:false,fingerprintEnabled:false,payWithIyzicoFirstTab:false,creditEnabled:true,payWithIyzicoLead:false,goBackUrl:\"\",metadata : {},createTag:function(){var iyziJSTag = document.createElement('script');iyziJSTag.setAttribute('src','https://sandbox-static.iyzipay.com/checkoutform/v2/bundle.js?v=1687112732810');document.head.appendChild(iyziJSTag);}};iyziInit.createTag();}</script>",
    "tokenExpireTime": 1800,
    "paymentPageUrl": "https://sandbox-cpp.iyzipay.com?token=a5b67652-c24a-4347-b61e-6c957bf30f1b&lang=en",
    "payWithIyzicoPageUrl": "https://sandbox-ode.iyzico.com/?token=a5b67652-c24a-4347-b61e-6c957bf30f1b&lang=en"
}
```

{% endcode %}

### Adım 2 - Token + URL

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

Bu adımda, önceki adımda aldığınız yanıttan token ve paymentPageUrl'yi çıkarmanız gerekir. Token daha sonra doğrulama için kaydedilmelidir ve kullanıcıyı ödeme sayfasına yönlendirmek için paymentPageUrl 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.
* **paymentPageUrl**; ödeme sayfasının kısaca göründüğü yer. `paymentPageUrl`'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ıda paymentPageUrl Arayüz Örneği;

<div align="left"><figure><img src="https://1970365243-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTpM8Bc8GIRKlQDusDr3%2Fuploads%2Fa4gHw8yvY5NtMzP8yt0E%2FScreen%20Shot%202023-06-18%20at%209.34.06%20PM.png?alt=media&#x26;token=4994ad78-56f4-4e1b-9e96-def0398664e4" alt=""><figcaption></figcaption></figure></div>

### Adım 3 - Yönlendirme

Yönlendirme aşaması, genel olarak [CF Başlatma](https://docs.iyzico.com/odeme-metotlari/odeme-formu/cf-entegrasyonu/cf-baslatma) ve [CF Sorgulama](https://docs.iyzico.com/odeme-metotlari/odeme-formu/cf-entegrasyonu/cf-sorgulama) adımlarını birbirine bağlar.

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

| Parametre ismi | Tip    | Açıklama                                                                                                      |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| **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. |

### Adım 4 - CF Sorgulama

**CF 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 CF Sorgulama istek yapısıdır.

#### **Örnek CF Sorgulama İsteği;**

{% code lineNumbers="true" %}

```json
{
    "locale": "en",
    "token": "a5b67652-c24a-4347-b61e-6c957bf30f1b",
    "conversationId": "sampleConversationId"
}
```

{% 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 CF Sorgulama Yanıtı;**

{% code lineNumbers="true" %}

```json
{
    "status": "success",
    "locale": "en",
    "systemTime": 1687113618054,
    "conversationId": "sampleConversationId",
    "price": 5.20000000,
    "paidPrice": 5.20000000,
    "installment": 1,
    "paymentId": "19831123",
    "fraudStatus": 1,
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0E-8,
    "iyziCommissionRateAmount": 0.20800000,
    "iyziCommissionFee": 0.25000000,
    "cardType": "CREDIT_CARD",
    "cardAssociation": "TROY",
    "cardFamily": "Cardfinans",
    "binNumber": "979203",
    "lastFourDigits": "0000",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "21097896",
            "transactionStatus": 2,
            "price": 5.20000000,
            "paidPrice": 5.20000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.20800000,
            "iyziCommissionFee": 0.25000000,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0E-8,
            "blockageResolvedDate": "2023-06-26 00:00:00",
            "subMerchantPrice": 0E-8,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0E-8,
            "merchantPayoutAmount": 4.74200000,
            "convertedPayout": {
                "paidPrice": 5.20000000,
                "iyziCommissionRateAmount": 0.20800000,
                "iyziCommissionFee": 0.25000000,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 4.74200000,
                "iyziConversionRate": 0E-8,
                "iyziConversionRateAmount": 0E-8,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "104530",
    "phase": "AUTH",
    "mdStatus": 1,
    "hostReference": "mock00037iyzihostrfn",
    "token": "3ee2d355-da4d-47ce-bd3d-13d8c1854128",
    "callbackUrl": "YOUR_CALLBACKURL",
    "paymentStatus": "SUCCESS"
}
```

{% endcode %}

{% 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 5 - Webhook

Webhook, uygulama düzenimizin en önemli konusudur.

Gerçek zamanlı ödeme bildirimleri almak, genel CF 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 CF Webhook**

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

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

[CF Sorgulama](https://docs.iyzico.com/odeme-metotlari/odeme-formu/cf-entegrasyonu/cf-sorgulama) yanıtı ve [Webhook](#a-dim-5-webhook) bildirimi birbirini doğrulamalıdır.

CF 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.

* CF 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 %}