Retrieve

Once the card details are entered in payment form and the “Pay X TL” button is pressed, iyzico is directed to the callbackUrl address -which is specified during the creation of the payment form- and a token value is posted to this address. A second query must then be made using this token. This second query allows viewing further details about the payment results. The value of the token to be used in this query can be acquired when the payment form is generated or when it is posted on your callbackUrl address by iyzico.

Request

Parameters to be sent to the service are as follows:

Input Name Type Mandatory Description
token String Yes Unique value created for each checkout form request. This token is used to access the payment result
locale String No Language (default: tr)
conversationId String No Conversation ID to match request and response

Response

Parameters to be returned from the service are as follows:

Output Name Type Description
status String Service response result (success / failure)
errorCode String Error code if service response status is failure
errorMessage String Error message if service response status is failure
errorGroup String Error group if service response status is failure
locale String Language (default: tr)
systemTime Long Response system timestamp value
conversationId String If set, conversation ID to match request and response
paymentId String ID of the payment. Merchants should keep payment ID in their system (this ID will be used for cancel requests)
price Decimal Total amount of basket. The sum of basket items’ amount must be equal to the price of basket
paidPrice Decimal Final amount (including installment fee) that will be charged to customer’s card. Merchants should store this value in their system
currency String Currency of request
installment Integer Installment number of payment, for single payments it returns 1. Valid values are 1, 2, 3, 6, 9, 12
basketId String Merchant's basket ID
binNumber String First 6 digit of card
cardAssociation String Valid values are VISA, MASTER_CARD, AMERICAN_EXPRESS, TROY
cardFamily String Valid values are Bonus, Axess, World, Maximum, Paraf, CardFinans, Advantage
cardType String Valid values are CREDIT_CARD, DEBIT_CARD, PREPAID_CARD
fraudStatus Integer Fraud risk status for payment request (0 for review / 1 for accept)
iyziCommissionFee Decimal iyzico commission fee for payment transaction
iyziCommissionRateAmount Decimal iyzico commission rate amount for payment transaction
merchantCommissionRate Decimal Merchant commission rate (e.g. price=100 & paidPrice=110, then merchant commission rate = 10)
merchantCommissionRateAmount Decimal Merchant commission rate amount (e.g. price=100 & paidPrice=110, then merchant commission rate amount = 10)
paymentTransactionId (ItemTransactions) String ID of basket item. Merchants should keep payment ID in their system (this ID will be used for cancel requests)
itemId(ItemTransactions) String Item ID of each item in basket
price(ItemTransactions) Decimal Item price of each item in basket
paidPrice(ItemTransactions) Decimal Captured amount from card based on each item. Merchants should keep paidPrice in their system
transactionStatus (ItemTransactions) Integer Status of a payment transaction. (0 for waiting / -1 for rejected by fraud / 1 for waiting for approval / 2 for approved
blockageRate(ItemTransactions) Decimal Blockage rate based on each item.
blockageRateAmountMerchant(ItemTransactions) Decimal Blockage rate amount for merchant based on each item
blockageResolvedDate(ItemTransactions) String Blockage resolve date based on each item. Date format should be “2015-10-19 14:36:52”
iyziCommissionFee(ItemTransactions) Decimal iyzico commission fee based on each item
iyziCommissionRateAmount(ItemTransactions) Decimal iyzico commission rate amount based on each item
merchantCommissionRate(ItemTransactions) Decimal Merchant commission rate (e.g. price=100 & paidPrice=110, then merchant commission rate = 10)
merchantCommissionRateAmount(ItemTransactions) Decimal Merchant commission rate amount (e.g. price=100 & paidPrice=110, then merchant commission rate amount = 10)
merchantPayoutAmount(ItemTransactions) Decimal Payout amount for each item transaction. This is the amount that remains after after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions)
paidPrice(ItemTransactions)(convertedPayout) Decimal Converted charged amount to card based on each item. Merchants should keep paidPrice in their system.
iyziCommissionFee(ItemTransactions)(convertedPayout) Decimal Converted iyzico commission fee based on each item
iyziCommissionRateAmount(ItemTransactions)(convertedPayout) Decimal Converted iyzico commission rate amount based on each item
blockageRateAmountMerchant(ItemTransactions)(convertedPayout) Decimal Converted blockage rate amount for merchant based on each item
merchantPayoutAmount(ItemTransactions)(convertedPayout) Decimal Converted payout amount for each item transaction. This the amount that remains after substracting iyzicoCommissionRateAmount, iyzicoCommissionFee and blockageRateAmountMerchant from paidPrice(ItemTransactions)
iyziConversationRate(ItemTransactions)(convertedPayout) Decimal iyzico conversation rate
iyziConversationRateAmount(ItemTransactions)(convertedPayout) Decimal iyzico conversation rate amount
currency(ItemTransactions)(convertedPayout) String Currency for payout conversion

Sample Codes

Sample codes that can be found in iyzico clients:

$request = new \Iyzipay\Request\RetrieveCheckoutFormRequest();
$request->setLocale(\Iyzipay\Model\Locale::TR);
$request->setConversationId("123456789");
$request->setToken("token");

$checkoutForm = \Iyzipay\Model\CheckoutForm::retrieve($request, Config::options());
RetrieveCheckoutFormRequest request = new RetrieveCheckoutFormRequest();
request.ConversationId = "123456789";
request.Token = "token";

CheckoutForm checkoutForm = CheckoutForm.Retrieve(request, options);
RetrieveCheckoutFormRequest request = new RetrieveCheckoutFormRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setToken("token");

CheckoutForm checkoutForm = CheckoutForm.retrieve(request, options);
iyzipay.checkoutForm.retrieve({
    locale: Iyzipay.LOCALE.TR,
    conversationId: '123456789',
    token: 'token'
}, function (err, result) {
    console.log(err, result);
    done();
});
request = {
    locale: 'tr',
    conversationId: '123456789',
    token: 'b4d8088e-ce35-452d-94c9-d5bd9f385557'
}
checkout_form_payment = Iyzipay::Model::CheckoutForm.new.retrieve(request, @options)
request = dict([('locale', 'tr')])
request['conversationId'] = '123456789'
request['token'] = 'token'

checkout_form_auth = iyzipay.CheckoutFormAuth()
checkout_form_auth_response = checkout_form_auth.retrieve(request, options)
//Request
{
    "locale": "tr",
    "conversationId": "123456789",
    "token": "d9a1d90e-7cfb-4ead-a6ec-34237bac04f0"
}

//Response
{
    "status": "success",
    "locale": "tr",
    "systemTime": 1470731191116,
    "conversationId": "123456789",
    "price": 1,
    "paidPrice": 1.2,
    "installment": 1,
    "paymentId": "26143",
    "fraudStatus": 1,
    "merchantCommissionRate": 20,
    "merchantCommissionRateAmount": 0.2,
    "iyziCommissionRateAmount": 0.0354,
    "iyziCommissionFee": 0.25,
    "cardType": "CREDIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamily": "Cardfinans",
    "cardToken": "mIbv1i4Tkjhmp/7BQQWa6zjeebQ=",
    "cardUserKey": "ycXvjM2Z/n94gk7MIc3JoamsDKk=",
    "binNumber": "531157",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "38226",
            "transactionStatus": 2,
            "price": 0.3,
            "paidPrice": 0.36,
            "merchantCommissionRate": 20,
            "merchantCommissionRateAmount": 0.06,
            "iyziCommissionRateAmount": 0.01062,
            "iyziCommissionFee": 0.075,
            "blockageRate": 10,
            "blockageRateAmountMerchant": 0.036,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2016-08-16 11:25:58",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 0.23838,
            "convertedPayout": {
                "paidPrice": 0.36,
                "iyziCommissionRateAmount": 0.01062,
                "iyziCommissionFee": 0.075,
                "blockageRateAmountMerchant": 0.036,
                "blockageRateAmountSubMerchant": 0,
                "subMerchantPayoutAmount": 0,
                "merchantPayoutAmount": 0.23838,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        },
        {
            "itemId": "BI102",
            "paymentTransactionId": "38227",
            "transactionStatus": 2,
            "price": 0.5,
            "paidPrice": 0.6,
            "merchantCommissionRate": 20,
            "merchantCommissionRateAmount": 0.1,
            "iyziCommissionRateAmount": 0.0177,
            "iyziCommissionFee": 0.125,
            "blockageRate": 10,
            "blockageRateAmountMerchant": 0.06,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2016-08-16 11:25:58",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 0.3973,
            "convertedPayout": {
                "paidPrice": 0.6,
                "iyziCommissionRateAmount": 0.0177,
                "iyziCommissionFee": 0.125,
                "blockageRateAmountMerchant": 0.06,
                "blockageRateAmountSubMerchant": 0,
                "subMerchantPayoutAmount": 0,
                "merchantPayoutAmount": 0.3973,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        },
        {
            "itemId": "BI103",
            "paymentTransactionId": "38228",
            "transactionStatus": 2,
            "price": 0.2,
            "paidPrice": 0.24,
            "merchantCommissionRate": 20,
            "merchantCommissionRateAmount": 0.04,
            "iyziCommissionRateAmount": 0.00708,
            "iyziCommissionFee": 0.05,
            "blockageRate": 10,
            "blockageRateAmountMerchant": 0.024,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2016-08-16 11:25:58",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 0.15892,
            "convertedPayout": {
                "paidPrice": 0.24,
                "iyziCommissionRateAmount": 0.00708,
                "iyziCommissionFee": 0.05,
                "blockageRateAmountMerchant": 0.024,
                "blockageRateAmountSubMerchant": 0,
                "subMerchantPayoutAmount": 0,
                "merchantPayoutAmount": 0.15892,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        }
    ],
    "token": "d9a1d90e-7cfb-4ead-a6ec-34237bac04f0",
    "callbackUrl": "https://www.merchant.com/callback",
    "paymentStatus": "SUCCESS"
}

Questions

If you have questions about this service, get in touch with us and find out how we can help you.