CF-Retrieve

When the card details are entered in the payment form and the "Pay X TL" button is pressed, iyzico will redirect to the callbackUrl address that you specified during the creation of the payment form. At this address, a token value will be posted by iyzico. To view additional details about the payment results, a second query must be made using this token.

Following service represents the usage of token;

Checkout Form (CF) Retrieve

post

After the CF payment form is completed, queries the result using the token.

Header parameters

AuthorizationstringRequired

Authorization header that starts with IYZWSv2 and is a signed hash generated in Base64 format.

Example: IYZWSv2 aXBzaWduYXR1cmU...

Content-TypestringRequired

Content-Type value.

Example: application/json

Body

localestring · enumOptional

Language code. Default is tr.

Example: enPossible values:

conversationIdstringOptional

Request/response correlation ID. The value sent in the request is returned unchanged in the response.

Example: 8152109759

tokenstringRequired

Token returned in the CF initialize response.

Example: 077aff05-1e9b-44aa-aa11-c268bb8b3826

Responses

200

Successful response (payment completed)

application/json

statusstring · enumOptional

Result of the request.

Example: successPossible values:

localestringOptional

Response language.

Example: en

systemTimeintegerOptional

System time (epoch ms).

Example: 1755536577419

conversationIdstringOptional

Correlation ID that matches the request.

Example: 8152109759

pricedecimalOptional

Basket total amount.

Example: 6

paidPricedecimalOptional

Total charged amount.

Example: 6

installmentintegerOptional

Number of installments.

Example: 1

paymentIdstringOptional

Payment ID.

Example: 24478123

fraudStatusinteger · enumOptional

Payment status according to fraud filters. If the risk score is low, the payment is approved immediately; if the risk score is high, the payment is rejected. The merchant should ship only when the value is 1; for 0, wait for notification.

1: Approved
0: In review
-1: Rejected

Example: 1Possible values:

merchantCommissionRatedecimalOptional

Merchant’s installment/commission rate. For example, if price=100 and paidPrice=110, the rate is 10%. Informational.

Example: 0

merchantCommissionRateAmountdecimalOptional

Merchant’s installment/commission amount. Example; 10 when price=100 and paidPrice=110. Informational.

Example: 0

iyziCommissionRateAmountdecimalOptional

iyzico processing commission amount for the payment.

Example: 0.2094

iyziCommissionFeedecimalOptional

iyzico processing fee for the payment.

Example: 0.25

cardTypestring · enumOptional

Card type.

Example: CREDIT_CARDPossible values:

cardAssociationstring · enumOptional

Card brand.

Example: MASTER_CARDPossible values:

cardFamilystring · enumOptional

Card family.

Example: AxessPossible values:

binNumberstringOptional

BIN (first 8 digits).

Example: 552608

lastFourDigitsstringOptional

Last 4 digits of the card.

Example: 0006

basketIdstringOptional

Basket ID.

Example: basketId

currencystring · enumOptional

Currency of the payment.

Example: TRYPossible values:

authCodestringOptional

Authorization code returned by the bank.

Example: 930115

phasestringOptional

Payment phase.

Example: AUTH

hostReferencestringOptional

Bank-provided host reference value for the payment.

Example: mock00007iyzihostrfn

signaturestringOptional

Signature value that can be used for integrity verification.

Example: 1960256fa0406e6ca0e02a71a9d0b3bd72c2aad4e2677cd315975a4dc8ecfaa5

tokenstringOptional

Checkout Form token value.

Example: 077aff05-1e9b-44aa-aa11-c268bb8b3826

callbackUrlstringOptional

Callback URL.

Example: https://callback.com/test

paymentStatusstringOptional

Result of the payment.

Example: SUCCESS

400

Failed response

application/json

post/payment/iyzipos/checkoutform/auth/ecom/detail

POST https://api.iyzipay.com/payment/iyzipos/checkoutform/auth/ecom/detail
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib....E0OGI1MTE=
Content-Type: application/json

{
  "locale": "en",
  "conversationId": "8152109759",
  "token": "077aff05-1e9b-44aa-aa11-c268bb8b3826"
}

{
  "status": "success",
  "locale": "en",
  "systemTime": 1755536577419,
  "conversationId": "8152109759",
  "price": 6,
  "paidPrice": 6,
  "installment": 1,
  "paymentId": "24478123",
  "fraudStatus": 1,
  "merchantCommissionRate": 0,
  "merchantCommissionRateAmount": 0,
  "iyziCommissionRateAmount": 0.2094,
  "iyziCommissionFee": 0.25,
  "cardType": "CREDIT_CARD",
  "cardAssociation": "MASTER_CARD",
  "cardFamily": "Axess",
  "binNumber": "552608",
  "lastFourDigits": "0006",
  "basketId": "basketId",
  "currency": "TRY",
  "itemTransactions": [
    {
      "itemId": "BI101",
      "paymentTransactionId": "26475993",
      "transactionStatus": 2,
      "price": 1,
      "paidPrice": 1,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.0349,
      "iyziCommissionFee": 0.04166667,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-07-20 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 0.92343333,
      "convertedPayout": {
        "paidPrice": 1,
        "iyziCommissionRateAmount": 0.0349,
        "iyziCommissionFee": 0.04166667,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 0.92343333,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    },
    {
      "itemId": "BI103",
      "paymentTransactionId": "26475995",
      "transactionStatus": 2,
      "price": 3,
      "paidPrice": 3,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.1047,
      "iyziCommissionFee": 0.125,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-07-20 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 2.7703,
      "convertedPayout": {
        "paidPrice": 3,
        "iyziCommissionRateAmount": 0.1047,
        "iyziCommissionFee": 0.125,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 2.7703,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    },
    {
      "itemId": "BI102",
      "paymentTransactionId": "26475994",
      "transactionStatus": 2,
      "price": 2,
      "paidPrice": 2,
      "merchantCommissionRate": 0,
      "merchantCommissionRateAmount": 0,
      "iyziCommissionRateAmount": 0.0698,
      "iyziCommissionFee": 0.08333333,
      "blockageRate": 0,
      "blockageRateAmountMerchant": 0,
      "blockageRateAmountSubMerchant": 0,
      "blockageResolvedDate": "2025-07-20 00:00:00",
      "subMerchantPrice": 0,
      "subMerchantPayoutRate": 0,
      "subMerchantPayoutAmount": 0,
      "merchantPayoutAmount": 1.84686667,
      "convertedPayout": {
        "paidPrice": 2,
        "iyziCommissionRateAmount": 0.0698,
        "iyziCommissionFee": 0.08333333,
        "blockageRateAmountMerchant": 0,
        "blockageRateAmountSubMerchant": 0,
        "subMerchantPayoutAmount": 0,
        "merchantPayoutAmount": 1.84686667,
        "iyziConversionRate": 0,
        "iyziConversionRateAmount": 0,
        "currency": "TRY"
      }
    }
  ],
  "authCode": "930115",
  "phase": "AUTH",
  "hostReference": "mock00007iyzihostrfn",
  "signature": "1960256fa0406e6ca0e02a71a9d0b3bd72c2aad4e2677cd315975a4dc8ecfaa5",
  "token": "077aff05-1e9b-44aa-aa11-c268bb8b3826",
  "callbackUrl": "https://callback.com/test",
  "paymentStatus": "SUCCESS"
}

Sample Codes

PreviousCF-Initialize

NextCF Sample Imp.

Last updated 10 months ago