CF Sample Imp.
In this document, we will delve into the comprehensive Implementation Steps of CF with Redirection Form 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:
Pair of API & Secret keys
A software tool to manage API calls; Postman, Insonmina, Github clients
If so, keep going.
Overview
The implementation of CF 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
Step 1 - CF Initialize
CF implementation begins with 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 CF-Initialize request body.
Sample CF-Initialize Request;
{
"locale":"en",
"conversationId":"sampleConversationId",
"price":"5.2",
"basketId":"B67832",
"paymentGroup":"PRODUCT",
"buyer":{
"id":"BY789",
"name":"Higher",
"surname":"Faster",
"identityNumber":"74300864791",
"email":"[email protected]",
"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
]
}
Once you have triggered above request, there are 3(three) scenarios you will monitor mostly.
Happy path includes a variable called, paymentPageUrl
.
{
"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:\"[email protected]\",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"
}
Step 2 - Token + URL
Hereby, token
and paymentPageUrl
are essential knots of for the rest of payment journey.
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 topaymentPageUrl
provides an interface to accomplish checkouts safely for end-users.
An example of paymentPageUrl
interface on the browser;
paymentPageUrl
interface on the browser;
Step 3 - Redirection
Redirection phase ties CF-Initialize and 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;
token
String
Unique value created for each checkout form request. This token is used to access the payment result
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;
{
"locale": "en",
"token": "a5b67652-c24a-4347-b61e-6c957bf30f1b",
"conversationId": "sampleConversationId"
}
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;
{
"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"
}
Step 5 - Webhook
Webhooks are tail subject of our implementation streamline.
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.
Each payment event triggers webhooks;
In
15
seconds.Until your server responds with
200
.For every
10
minutes.Max
3
times.
Sample PWI Webhook
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 parameters optionally
CF-Retrieve response and Webhook notification have to authenticate each other.
It is crucial to cross-verify the response received from CF-Retrieve and the data received in the Webhook notification. Match the paymentId, status, price, and other relevant parameters to ensure the authenticity and correctness of the transaction.
paymentId
on CF-Retrieve response should be equal topaymentId
from WebhookBoth of the
status
parameters should besuccess
price
parameter amounts should be the sameAnd lastly, Idempotency parameters should be the same as well.
If so, congratulations! Just finished PWI implementation.
Transaction details could get from merchant panel.
Last updated