# CF Sample Imp.

In this document, we will delve into the comprehensive [Implementation Steps](https://docs.iyzico.com/en/payment-methods/checkoutform/cf-implementation/..#implementation-steps) of [CF](https://docs.iyzico.com/en/payment-methods/checkoutform) with [Redirection Form](https://iyzico-new-documentation.gitbook.io/iyzico-dokuemantasyon/payment-methods/cf-checkout-form/cf-implementation#redirection) and provide sample requests, responses, and best practices for a fast, easy, and secure integration.

### Pre-Requirements;

Before proceeding, please ensure that you have the following pre-requisites in place:

* [A sandbox account](https://docs.iyzico.com/en/getting-started/preliminaries/sandbox)
* [Pair of API & Secret keys](https://docs.iyzico.com/en/payment-methods/checkoutform/cf-implementation/broken-reference)
* A software tool to manage API calls; [Postman](https://docs.iyzico.com/en/getting-started/preliminaries/postman-collections), Insonmina, Github clients

If so, keep going.

### Overview

The implementation of [CF](https://docs.iyzico.com/en/payment-methods/checkoutform) requires two subsequent `POST` requests to be orchestrated one after the other.

In short;

* First, we will illustrate a **CF-Initialize** `POST` request.
* Then, we will cover up with **CF-Retrieve** `POST` section.

### Steps

1. [CF-Initialize](#step-1-cf-initialize)
2. [Token + URL](#step-2-token--url)
3. [Redirection](#step-3-redirection)
4. [CF-Retrieve](#step-4-cf-retrieve)
5. [Webhook](#step-5-webhook)

### Step 1 - CF Initialize

CF implementation begins with [PWI-Initialize](https://docs.iyzico.com/en/payment-methods/paywithiyzico/pwi-implementation/pwi-initialize) `POST` request.

This step involves sending a POST request and the request body contains various parameters such as locale, conversationId, price, basketId, paymentGroup, callbackUrl, currency, paidPrice, enabledInstallments, buyer details, shipping address, billing address, and basket items.

The following object is a sample C&#x46;**-Initialize** request body.

\
**Sample CF-Initialize Request;**

{% 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 %}

Once you have triggered above request, there are 3(three) scenarios you will monitor mostly.\
Happy path includes a variable called, `paymentPageUrl`.

{% 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 %}

### Step 2 - Token + URL

Hereby, `token` and `paymentPageUrl` are essential knots of for the rest of payment journey.&#x20;

In this step, you need to extract the token and `paymentPageUrl` from the response obtained in the previous step. The token should be saved for later validation, and the `paymentPageUrl` is used to redirect the user to the payment page.

* **token;** Its expected that merchants saves `token` parameter to confront and validate payment at the very end of payment journey.
* `paymentPageUrl`**;** where payment page appears briefly. Redirection to `paymentPageUrl` provides an interface to accomplish checkouts safely for end-users.

#### An example of `paymentPageUrl` interface on the browser;

<div align="left"><figure><img src="https://3756320043-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBnccQ14a3b6OedaJJFT4%2Fuploads%2FkJkl5He9egfTYtHoM4TM%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>

### Step 3 - Redirection

Redirection phase ties [CF-Initialize](https://docs.iyzico.com/en/payment-methods/checkoutform/cf-implementation/cf-initialize) and [CF-Retrieve](https://docs.iyzico.com/en/payment-methods/checkoutform/cf-implementation/cf-retrieve) steps overall.

Following up end user interact on CF payment page, iyzico will automatically redirect the page to the address given in the "callbackUrl" parameter. Redirection `POST`  includes;

| Input Name | Type   | Description                                                                                          |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------- |
| **token**  | String | Unique value created for each checkout form request. This token is used to access the payment result |

{% hint style="info" %}

{% endhint %}

### Step 4 - CF Retrieve

**CF-Retrieve** is the last step of PWI chain.

Basically, we have just accepted a payment on the previous step.\
It is now time to legalize the transaction in this step.\
The following example is a sample **CF-Retrieve** request body.

**Sample CF-Retrieve Request;**

{% code lineNumbers="true" %}

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

{% endcode %}

Once you have triggered above request, there are 2(two) scenarios you will monitor mostly.\
Happy path includes `SUCCESS` parameter in the `paymentStatus` variable.

**Sample CF-Retrieve Response;**

{% 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` parameter will only appear on 3DS operations.

Please check further details around mdStatus [here](https://iyzico-new-documentation.gitbook.io/iyzico-dokuemantasyon/payment-methods/3ds/3ds-implementation#mdstatuses).
{% endhint %}

### Step 5 - Webhook

Webhooks are tail subject of our implementation streamline.&#x20;

Receiving real-time payment notifications leverages overall CF experience while ensuring that the notifications are coming from trusted sources, preventing any potential tampering or unauthorized access to sensitive data.&#x20;

Each payment event triggers webhooks;&#x20;

* In `15` seconds.&#x20;
* Until your server responds with `200`.
* For every `10` minutes.
* Max `3` times.

**Sample PWI Webhook**

| Parametere                | Type   | Description                                                           |
| ------------------------- | ------ | --------------------------------------------------------------------- |
| **iyziEventTime**         | long   | Unix timestamp value of first notification.                           |
| **iyziEventType**         | string | Shows the request type. Values: API\_AUTH, THREE\_DS\_AUTH, BKM\_AUTH |
| **iyziReferenceCode**     | string | A unique reference code for the notification                          |
| **paymentId**             | long   | Unique iyzico reference code of related payment                       |
| **paymentConversationId** | string | Merchant's reference id for the related payment                       |
| **status**                | string | Payment status. Values: SUCCESS, FAILURE                              |

Happy path includes `success` parameter in the `status` variable.

#### Confirmation

To finalize payment operations successfully, correlation of certain variables plays significant role;

* `paymentId`
* `status`
* `price`
* Other [Idempotency](file:///iyzico-dokuemantasyon/getting-started/preliminaries/idempotency) parameters optionally

&#x20;

[CF-Retrieve](https://docs.iyzico.com/en/payment-methods/checkoutform/cf-implementation/cf-retrieve) response and [Webhook](file:///iyzico-dokuemantasyon/advanced/webhook) notification have to authenticate each other.

It is crucial to cross-verify the response received from [CF-Retrieve](https://docs.iyzico.com/en/payment-methods/api/non-3ds/non-3ds-implementation/retrieve) and the data received in the [Webhook](https://docs.iyzico.com/en/advanced/webhook) notification. Match the paymentId, status, price, and other relevant parameters to ensure the authenticity and correctness of the transaction.

* `paymentId` on [CF-Retrieve](https://docs.iyzico.com/en/payment-methods/checkoutform/cf-implementation/cf-retrieve) response should be equal to `paymentId`from Webhook
* Both of the `status` parameters should be `success`
* `price` parameter amounts should be the same
* And lastly, Idempotency parameters should be the same as well.

&#x20;

If so, congratulations! Just finished PWI implementation.

Transaction details could get from merchant panel.

{% hint style="info" %}
Please note that the provided sample requests and responses are for illustration purposes only, and you should adapt them to your specific implementation requirements and API documentation.
{% endhint %}
