3DS Implementation

Integration Flow

Steps

BIN Check
Init 3DS
"threeDSHtmlContent" Decode
Redirection
Auth 3DS
Webhook

Top View

BIN Check; section of identifying issuer details where API returns information about installment options and card details.
Init 3DS; first POST request of managing two-step 3DS transactions.
"threeDSHtmlContent"; base64 encrypted HTML page where your end-user expected to validate 3DS page OTP verification.
Redirection; Following up consumers' payment, PayU iyzico triggers correlated IPN(Instant Payment Notification) to given callbackUrl.
Auth 3DS; engage step to officialize transaction between Acquirer and Issuer.
Webhook; real-time notification of relevant payment.

Sample Implementation

3DS implementation consists of 2 subsequent POST requests in short.

Suggested integration tracks following order;

1. BIN Check

Whether 3DS or NON-3DS payment method, It is advised to identify issuer card feature beforehand. BIN detail services provides further details of card type, card scheme, card association which indicates installment and 3DS features.

Sample Retrieve Installment Request;

{
  "price":"100.0",
  "binNumber":"535805"
}

Sample Retrieve Installment Response;

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1685905139724,
    "installmentDetails": [
        {
            "binNumber": "535805",
            "price": 100.0,
            "cardType": "DEBIT_CARD",
            "cardAssociation": "MASTER_CARD",
            "cardFamilyName": "iyzico DC",
            "force3ds": 0,
            "bankCode": 864,
            "bankName": "iyzico",
            "forceCvc": 0,
            "commercial": 0,
            "dccEnabled": 0,
            "installmentPrices": [
                {
                    "installmentPrice": 100.0,
                    "totalPrice": 100.0,
                    "installmentNumber": 1
                }
            ]
        }
    ]
}

2. Init 3DS

3DS payment journey begins with Init 3DS POST request.

Sample Init 3DS Request;

{
    "locale": "en",
    "price": "3.2",
    "paidPrice": "3.2",
    "installment": 1,
    "paymentChannel": "WEB",
    "basketId": "B67832",
    "paymentGroup": "PRODUCT",
    "paymentCard": {
        "cardHolderName": "Dev PayU iyzico",
        "cardNumber": "5526080000000006",
        "expireYear": "2023",
        "expireMonth": "11",
        "cvc": "200"
    },
    "buyer": {
        "id": "BY789",
        "name": "John",
        "surname": "Doe",
        "identityNumber": "74300864791",
        "email": "email@email.com",
        "gsmNumber": "+905350000000",
        "registrationDate": "2013-04-21 15:12:09",
        "lastLoginDate": "2015-10-05 12:43:35",
        "registrationAddress": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
        "city": "Istanbul",
        "country": "Turkey",
        "zipCode": "34732",
        "ip": "85.34.78.112"
    },
    "conversationId": "devPayUiyzico",
    "shippingAddress": {
        "address": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
        "zipCode": "34742",
        "contactName": "Jane Doe",
        "city": "Istanbul",
        "country": "Turkey"
    },
    "billingAddress": {
        "address": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
        "zipCode": "34742",
        "contactName": "Jane Doe",
        "city": "Istanbul",
        "country": "Turkey"
    },
    "basketItems": [
        {
            "id": "BI101",
            "price": "1.1",
            "name": "Binocular",
            "category1": "Collectibles",
            "category2": "Accessories",
            "itemType": "PHYSICAL"
        },
        {
            "id": "BI1012",
            "price": "2.1",
            "name": "Binocular",
            "category1": "Collectibles",
            "category2": "Accessories",
            "itemType": "PHYSICAL"
        }
    ],
    "currency": "TRY",
    "callbackUrl": "https://devPayUiyzico.com/"
}n

In return It is expected to receive "threeDSHtmlContent" key-value with other pieces;

Sample Init 3DS Response;

{
    "status": "success",
    "locale": "en",
    "systemTime": 1685539494559,
    "conversationId": "devPayUiyzico",
    "threeDSHtmlContent": "PCFkb2N0eXBlIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KPGhlYWQ+CiAgICA8dGl0bGU+aXl6aWNvIE1vY2sgM0QtU2VjdXJlIFByb2Nlc3NpbmcgUGFnZTwvdGl0bGU+CjwvaGVhZD4KPGJvZHk+Cjxmb3JtIGlkPSJpeXppY28tM2RzLWZvcm0iIGFjdGlvbj0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L21vY2svaW5pdDNkcyIgbWV0aG9kPSJwb3N0Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9Im9yZGVySWQiIHZhbHVlPSJtb2NrNDYtNjg3NjU1ODAwODI2MjM5NWl5emlvcmQiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iYmluIiB2YWx1ZT0iNTUyNjA4Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9InN1Y2Nlc3NVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9zdWNjZXNzLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImZhaWx1cmVVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9mYWlsdXJlLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImNvbmZpcm1hdGlvblVybCIgdmFsdWU9Imh0dHBzOi8vc2FuZGJveC1hcGkuaXl6aXBheS5jb20vcGF5bWVudC9tb2NrL2NvbmZpcm0zZHMiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iUGFSZXEiIHZhbHVlPSJjYWIxNjA0YS02MWJiLTQ0NGQtOGExNS1kZDZmMzhjZGRiNjMiPgo8L2Zvcm0+CjxzY3JpcHQgdHlwZT0idGV4dC9qYXZhc2NyaXB0Ij4KICAgIGRvY3VtZW50LmdldEVsZW1lbnRCeUlkKCJpeXppY28tM2RzLWZvcm0iKS5zdWJtaXQoKTsKPC9zY3JpcHQ+CjwvYm9keT4KPC9odG1sPg=="
}

3. "threeDSHtmlContent" Decode

"threeDSHtmlContent" represents encrypted 3DS form itself.

Once we render encoded "threeDSHtmlContent" parameter from Init 3DS response on the browser, 3DS screen will display in front of the consumer.

Decoded "threeDSHtmlContent" Sandbox Sample;

"threeDSHtmlContent": "PCFkb2N0eXBlIGh0bWw+CjxodG1sIGxhbmc9ImVuIj4KPGhlYWQ+CiAgICA8dGl0bGU+aXl6aWNvIE1vY2sgM0QtU2VjdXJlIFByb2Nlc3NpbmcgUGFnZTwvdGl0bGU+CjwvaGVhZD4KPGJvZHk+Cjxmb3JtIGlkPSJpeXppY28tM2RzLWZvcm0iIGFjdGlvbj0iaHR0cHM6Ly9zYW5kYm94LWFwaS5peXppcGF5LmNvbS9wYXltZW50L21vY2svaW5pdDNkcyIgbWV0aG9kPSJwb3N0Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9Im9yZGVySWQiIHZhbHVlPSJtb2NrNDYtNjg3NjU1ODAwODI2MjM5NWl5emlvcmQiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iYmluIiB2YWx1ZT0iNTUyNjA4Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9InN1Y2Nlc3NVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9zdWNjZXNzLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImZhaWx1cmVVcmwiIHZhbHVlPSJodHRwczovL3NhbmRib3gtYXBpLml5emlwYXkuY29tL3BheW1lbnQvaXl6aXBvcy9jYWxsYmFjazNkcy9mYWlsdXJlLzI3Ij4KICAgIDxpbnB1dCB0eXBlPSJoaWRkZW4iIG5hbWU9ImNvbmZpcm1hdGlvblVybCIgdmFsdWU9Imh0dHBzOi8vc2FuZGJveC1hcGkuaXl6aXBheS5jb20vcGF5bWVudC9tb2NrL2NvbmZpcm0zZHMiPgogICAgPGlucHV0IHR5cGU9ImhpZGRlbiIgbmFtZT0iUGFSZXEiIHZhbHVlPSJjYWIxNjA0YS02MWJiLTQ0NGQtOGExNS1kZDZmMzhjZGRiNjMiPgo8L2Zvcm0+CjxzY3JpcHQgdHlwZT0idGV4dC9qYXZhc2NyaXB0Ij4KICAgIGRvY3VtZW50LmdldEVsZW1lbnRCeUlkKCJpeXppY28tM2RzLWZvcm0iKS5zdWJtaXQoKTsKPC9zY3JpcHQ+CjwvYm9keT4KPC9odG1sPg=="

Encoded "threeDSHtmlContent" Sandbox Sample;

<!doctype html>
<html lang="en">
<head>
    <title>iyzico Mock 3D-Secure Processing Page</title>
</head>
<body>
<form id="iyzico-3ds-form" action="https://sandbox-api.iyzipay.com/payment/mock/init3ds" method="post">
    <input type="hidden" name="orderId" value="mock46-6876558008262395iyziord">
    <input type="hidden" name="bin" value="552608">
    <input type="hidden" name="successUrl" value="https://sandbox-api.iyzipay.com/payment/iyzipos/callback3ds/success/27">
    <input type="hidden" name="failureUrl" value="https://sandbox-api.iyzipay.com/payment/iyzipos/callback3ds/failure/27">
    <input type="hidden" name="confirmationUrl" value="https://sandbox-api.iyzipay.com/payment/mock/confirm3ds">
    
    <input type="hidden" name="PaReq" value="cab1604a-61bb-444d-8a15-dd6f38cddb63">
    <input type="hidden" name="termUrl" value="cab1604a-61bb-444d-8a15-dd6f38cddb63">
    <input type="hidden" name="md" value="cab1604a-61bb-444d-8a15-dd6f38cddb63">
    
</form>
<script type="text/javascript">
    document.getElementById("iyzico-3ds-form").submit();
</script>
</body>
</html>

An example of decoded threeDSHtmlContent interface on the browser;

4. Redirection

Redirection phase ties Init 3DS and Auth 3DS steps overall.

Following up cardholder OTP(One Time Password) confirmation PayU 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)
paymentId	String	If verification is successful, iyzico will return a paymentid. It must be set in Auth request
conversationData	String	If verification is successful, iyzico might return. If returns, it must be set in Auth request
conversationId	Long	If set, conversation ID to match request and response
mdStatus	String	1 for successful payment, 0,2,3,4,5,6,7,8 for failure payments

Input Name

Type

Description

status

String

Service response result (success / failure)

paymentId

String

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

conversationData

String

If verification is successful, iyzico might return. If returns, it must be set in Auth request

conversationId

Long

If set, conversation ID to match request and response

mdStatus

String

1 for successful payment, 0,2,3,4,5,6,7,8 for failure payments

mdStatuses

"mdStatus" interprets merchant plug-in responses on 3DS triangle.

While successful 3DS operations results with "mdStatus":"1" on "callbackUrl", failure scenarios might have one of the items from list below;

mdStatus	Description
mdStatus = 0	Invalid 3D Secure signature or verification
mdStatus = 2	Card holder or Issuer not registered to 3D Secure network
mdStatus = 3	Issuer is not registered to 3D secure network
mdStatus = 4	Verification is not possible, card holder chosen to register later on system
mdStatus = 5	Verification is not possbile
mdStatus = 6	3D Secure error
mdStatus = 7	System error
mdStatus = 8	Unknown card

mdStatus

Description

mdStatus = 0

Invalid 3D Secure signature or verification

mdStatus = 2

Card holder or Issuer not registered to 3D Secure network

mdStatus = 3

Issuer is not registered to 3D secure network

mdStatus = 4

Verification is not possible, card holder chosen to register later on system

mdStatus = 5

Verification is not possbile

mdStatus = 6

3D Secure error

mdStatus = 7

System error

mdStatus = 8

Unknown card

5. Auth 3DS

After having completing all the steps above, Its now time to officialize payment operation between Issuer and Acquirer with Auth 3DS request.

Sample Init 3DS Request;

{
  "paymentId": "123456789"
}

Sample Init 3DS Response;

{
    "status": "success",
    "locale": "tr",
    "systemTime": 1685539637584,
    "price": 3.20000000,
    "paidPrice": 3.20000000,
    "installment": 1,
    "paymentId": "123456789",
    "fraudStatus": 1,
    "merchantCommissionRate": 0E-8,
    "merchantCommissionRateAmount": 0E-8,
    "iyziCommissionRateAmount": 0.12800000,
    "iyziCommissionFee": 0.25000000,
    "cardType": "DEBIT_CARD",
    "cardAssociation": "MASTER_CARD",
    "cardFamilyName": "iyzico DC",
    "binNumber": "535805",
    "lastFourDigits": "0006",
    "basketId": "B67832",
    "currency": "TRY",
    "itemTransactions": [
        {
            "itemId": "BI101",
            "paymentTransactionId": "123456789",
            "transactionStatus": 2,
            "price": 1.10000000,
            "paidPrice": 1.10000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.04400000,
            "iyziCommissionFee": 0.08593750,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2023-06-08 00:00:00",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 0.97006250,
            "convertedPayout": {
                "paidPrice": 1.10000000,
                "iyziCommissionRateAmount": 0.04400000,
                "iyziCommissionFee": 0.08593750,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 0.97006250,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        },
        {
            "itemId": "BI1012",
            "paymentTransactionId": "123456788",
            "transactionStatus": 2,
            "price": 2.10000000,
            "paidPrice": 2.10000000,
            "merchantCommissionRate": 0E-8,
            "merchantCommissionRateAmount": 0E-8,
            "iyziCommissionRateAmount": 0.08400000,
            "iyziCommissionFee": 0.16406250,
            "blockageRate": 0E-8,
            "blockageRateAmountMerchant": 0E-8,
            "blockageRateAmountSubMerchant": 0,
            "blockageResolvedDate": "2023-06-08 00:00:00",
            "subMerchantPrice": 0,
            "subMerchantPayoutRate": 0E-8,
            "subMerchantPayoutAmount": 0,
            "merchantPayoutAmount": 1.85193750,
            "convertedPayout": {
                "paidPrice": 2.10000000,
                "iyziCommissionRateAmount": 0.08400000,
                "iyziCommissionFee": 0.16406250,
                "blockageRateAmountMerchant": 0E-8,
                "blockageRateAmountSubMerchant": 0E-8,
                "subMerchantPayoutAmount": 0E-8,
                "merchantPayoutAmount": 1.85193750,
                "iyziConversionRate": 0,
                "iyziConversionRateAmount": 0,
                "currency": "TRY"
            }
        }
    ],
    "authCode": "905307",
    "phase": "AUTH",
    "mdStatus": 1,
    "hostReference": "mock00007iyzihostrfn"
}

mdStatus parameter will only appear on 3DS operations.

6. Webhook

Webhooks are tail subject of our implementation streamline.

Receiving real-time payment notifications leverages overall 3DS 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 Auth 3DS 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

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