LogoLogo
GitHubFeedback Form
EN
EN
  • GETTING STARTED
    • Welcome
    • Preliminaries
      • Sandbox
      • Authentication
        • HMACSHA256 Auth
      • Postman Collections
      • Live vs Sandbox
      • Idempotency
      • Limiters
  • Payment Methods
    • PayWithiyzico (PWI)
      • PWI Implementation
        • PWI-Initialize
        • PWI-Retrieve
        • PWI Sample Imp.
    • Direct Charge
      • Non-3DS
        • NON-3DS Implementation
          • Create Payment
          • Retrieve
      • 3DS
        • 3DS Implementation
          • Init 3DS
          • Auth 3DS
      • Checkout Form (CF)
        • CF Implementation
          • CF-Initialize
          • CF-Retrieve
          • CF Sample Imp.
    • PreAuth & Capture
      • Non-3DS
        • Non-3DS Implementation
          • Create PreAuth Payment
          • Create PostAuth Payment
  • Products
    • Online Payment
    • Marketplace
      • Marketplace Implementation
        • Submerchant
          • Submerchant Update
          • Retrieve Submerchant
          • Submerchant Price / Item Update
        • Online Payment
        • Approval
    • Subscription
      • Subscription Implementation
        • Subscription Product
        • Payment Plan
        • Subscription Transactions
        • Subscriber Transactions
    • Bank Transfer
      • Bank Transfer Implementation
        • Bank Transfer Init
        • Bank Transfer Retrieve
      • Bank Transfer FAQ
    • iyzilink
      • iyzilink API
    • Shopping Credit
      • Shopping Credit Implementation
        • Initialize Shopping Credit
        • Retrieve Shopping Credit
        • Shopping Credit Sample Imp.
  • Advanced
    • Card Storage
    • Reporting Service
    • Refund & Cancel
    • Webhook
    • SFTP
    • Settlement Files
    • Fraud Notifications
    • Installment & BIN Service
    • Refund to Balance
    • Retrieve Payment
    • Response Signature Validation
  • Platforms
    • Woocommerce
    • Opencart
    • Prestashop
    • Magento
    • IdeaSoft
    • Ticimax
    • T-Soft
    • Shopify
    • WIX
  • Add-ons
    • Error Codes
      • Bank Error Codes
    • Test Cards
    • Integration Checklist
    • iyzico Logo Pack
Powered by GitBook
On this page
  • Pre-Requirements;
  • Overview
  • Adımlar
  • Step 1 - PWI Initialize
  • Step 2 - Token + URL
  • Step 3 - Redirection
  • Step 4 - PWI Retrieve
  • Step 5 - Webhook
  1. Payment Methods
  2. PayWithiyzico (PWI)
  3. PWI Implementation

PWI Sample Imp.

PreviousPWI-RetrieveNextDirect Charge

Last updated 5 months ago

LogoLogo

Company

  • About
  • Career
  • Social
  • Youtube

Community

  • Github
  • Medium

Integration

  • Brand Guide
  • Solution Partners
  • Open Source

Contact

  • Contact Us
  • Support Center

Here at the page, we are going to look closer on of PWI comprehensively while providing sample requests, responses and best practices from fast, ease and secure implementation point of view.

Pre-Requirements;

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

  • A sandbox account

  • Pair of API & Secret keys

  • A software tool to manage API calls; Postman, Insonmina, Github clients

If so, keep going.

Overview

Implementation requires two subsequent POST requests orchestrate one by one.

In short;

  • First, we will illustrate a PWI-Initialize POST request.

  • Then, we will cover up with PWI-Retrieve POST section.

Adımlar

  1. PWI-Initialize

  2. Token + URL

  3. Redirection

  4. PWI-Retrieve

  5. Webhook

Step 1 - PWI Initialize

PWI implementation begins with PWI-Initialize POST request.

This step involves sending a POST request to initialize the PWI payment. 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 PWI-Initialize request body.

Sample PWI-Initialize Request;

{
    "locale": "en", //tr
    "conversationId": "conversationID",
    "price": "10.91",
    "basketId": "basketID",
    "paymentGroup": "OTHER",
    "callbackUrl": "YOUR_CALLBACKURL",
    "currency": "TRY",
    "paidPrice": "49.91",
    "enabledInstallments": [
        2,
        3,
        6,
        9,
        12
    ],
    "buyer": {
        "id": "buyerID",
        "name": "buyerName",
        "surname": "buyerSurname",
        "identityNumber": "11111111111",
        "email": "email@email.com",
        "gsmNumber": "+905350000000",
        "registrationAddress": "Burhaniye Mahallesi Atilla Sokak No:7 Üsküdar",
        "city": "Istanbul",
        "country": "Turkey",
        "ip": "85.34.78.112"
    },
    "shippingAddress": {
        "address": "Burhaniye Mahallesi Atilla Sokak No:7 Üsküdar",
        "contactName": "Contact Name",
        "city": "Istanbul",
        "country": "Turkey"
    },
    "billingAddress": {
        "address": "Burhaniye Mahallesi Atilla Sokak No:7 Üsküdar",
        "contactName": "Contact Name",
        "city": "Istanbul",
        "country": "Turkey"
    },
    "basketItems": [
        {
            "id": "ItemID",
            "price": "10.91",
            "name": "product Name",
            "category1": "Category Name",
            "itemType": "PHYSICAL"
        }
    ]
}

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

{
    "status": "success",
    "locale": "en", //tr
    "systemTime": 1619779710035,
    "conversationId": "123456789",
    "token": "a641ab63-0b7b-4a50-bb09-6c7325041acd",
    "tokenExpireTime": 1800,
    "payWithIyzicoPageUrl": "https://sandbox-consumer.iyzico.com/checkout?token=a641ab63-0b7b-4a50-bb09-6c7325041acd&lang=tr"
}

Step 2 - Token + URL

Hereby, token and payWithIyzicoPageUrl are essential knots of for the rest of payment journey.

In this step, you need to extract the token and payWithIyzicoPageUrl from the response obtained in the previous step. The token should be saved for later validation, and the payWithIyzicoPageUrl 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.

  • payWithIyzicoPageUrl; where payment page appears briefly. Redirection to payWithIyzicoPageUrl provides an interface to accomplish checkouts safely for end-users.

An example of payWithIyzicoPageUrl interface on the browser;

Step 3 - Redirection

Redirection phase ties PWI-Initialize and PWI-Retrieve steps overall.

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

Input Name
Type
Description

status

String

Service response result (success / failure)

iyziPaymentId

String

If verification is successful, iyzico will return a paymentid. It must be set in Auth request

merchantId

String

ID of your merchant identification.

paymentConversationId

Long

If set, conversation ID to match request and response

token

String

Unique value created for each checkout form request. This token is used to access the payment result

iyziReferenceCode

String

A unique reference code for the notification

iyziEventType

String

Shows the request type. Exepcted value is CHECKOUT_FORM_AUTH

mdStatus parameter will only appear on 3DS operations.

Please check further details around mdStatus here.

Step 4 - PWI Retrieve

PWI-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 PWI-Retrieve request body.

Sample PWI-Retrieve Request;

{
    "locale": "en", //tr
    "conversationId": "YOUR_CONVERSATION_ID",
    "token": "YOUR_TOKEN"
}

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 PWI-Retrieve Response;

{
    "status": "success",
    "locale": "en", //tr
    "systemTime": 1,
    "conversationId": "YOUR_CONVERSATION_ID",
    "price": 1,
    "paidPrice": 1,
    "installment": 1,
    "paymentId": "GENERIC_PAYMENT_ID",
    "fraudStatus": 1,
    "merchantCommissionRate": 1,
    "merchantCommissionRateAmount": 1,
    "iyziCommissionRateAmount": 1,
    "iyziCommissionFee": 1,
    "binNumber": "000000",
    "lastFourDigits": "0000",
    "basketId": "basketID",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "ItemID",
            "paymentTransactionId": "GENERIC_PAYMENT_TRANSACTION_ID",
            "transactionStatus": 2,
            "price": 1,
            "paidPrice": 1,
            "merchantCommissionRate": 1,
            "merchantCommissionRateAmount": 1,
            "iyziCommissionRateAmount": 1,
            "iyziCommissionFee": 1,
            "blockageRate": 1,
            "blockageRateAmountMerchant": 1,
            "blockageRateAmountSubMerchant": 1,
            "blockageResolvedDate": "GENERIC_DATE",
            "subMerchantPrice": 1,
            "subMerchantPayoutRate": 1,
            "subMerchantPayoutAmount": 1,
            "merchantPayoutAmount": 1,
            "convertedPayout": {
                "paidPrice": 1,
                "iyziCommissionRateAmount": 1,
                "iyziCommissionFee": 1,
                "blockageRateAmountMerchant": 1,
                "blockageRateAmountSubMerchant": 1,
                "subMerchantPayoutAmount": 1,
                "merchantPayoutAmount": 1,
                "iyziConversionRate": 1,
                "iyziConversionRateAmount": 1,
                "currency": "TRY"
            }
        }
    ],
    "phase": "AUTH",
    "token": "YOUR_TOKEN",
    "callbackUrl": "YOUR_CALLBACK_URL",
    "paymentStatus": "SUCCESS"
}

Step 5 - Webhook

Webhooks are tail subject of our implementation streamline.

Receiving real-time payment notifications leverages overall PWI 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

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 parameters optionally

PWI-Retrieve response and Webhook notification have to authenticate each other.

It is crucial to cross-verify the response received from PWI-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 PWI-Retrieve response should be equal to paymentIdfrom 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.

If so, congratulations! Just finished PWI implementation.

Transaction details could get from merchant panel.

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.

Implementation Steps