Universal Card Storage

Universal card storage feature allows merchants to get payments from their customer's saved cards.

Payment process with saved cards

1- To get the necessary information, you need to send email and gsmNumber information to this service. In the response, you can understand if your customer has a saved card or not. This service returns you a response including scriptType tag. You can see scriptType values below,

• CONSUMER_WITH_CARD_EXIST:   This value means that the customer has already a stored card.
• UCS_CONSENT:   This means that customer does not have a saved card.

2- If your customer has a stored card(scriptType:CONSUMER_WITH_CARD_EXIST), please follow the steps below

Script parameter in the response of UCS service should be printed in the webpage. This javascript loads related items for payments without card information.

• "<script type=\"text/javascript\">if (typeof iyziUcsInit == 'undefined') {var iyziUcsInit = {\"baseUrl\":\"https://sandbox-api.iyzipay.com\", \"buyerProtectedConsumer\":false,\"ucsToken\":\"3f971db9-897c-4c74-aa29-ed9b40644b12\",\"scriptType\":\"CONSUMER_WITH_CARD_EXIST\",\"buyerProtectedMerchant\":false,\"maskedGsmNumber\":\"+90********31\",\"gsmNumber\":\"+905557378631\",\"merchantName\":\"Sandbox Merchant Name - 58892\", createTag: function () {var iyziUcsJSTag = document.createElement('script'); iyziUcsJSTag.setAttribute('src', 'https://sandbox-static.iyzipay.com/checkoutform/v2/bundle.js?v=1575919444317'); document.head.appendChild(iyziUcsJSTag);}};if (typeof iyziInit == 'undefined') { iyziUcsInit.createTag(); }}</script>"

In your checkout form, put this div line to the related place

• <div id="ucs-cards"></div>

After you print the javascript and the div above, your website will load the screen below into the ucs-cards div. If your customer continues the process, he/she will be asked to make an OTP-SMS to access the stored cards.

At this step, your web page also loads a javascript object called universalCardStorage. You can find detailed information about this object in next steps.

After your customer passes the OTP, the screen is updated as below and it shows the saved cards of your customer.

You can think this page as a form. You can put a button to a related area and whenever your customer clicks the button, you can check the values of universalCardStorage object. The payment flow can be processed according to values in universalCardStorage.

universalCardStorage: This javascript object is loaded as soon as you called the UCS service. To be able to follow all process you can check this object if any action has been taken on your payment form. It has 4 parameters. If your customer already has stored cards, registerConsumerCard parameter will be True. Otherwise, by default registerConsumerCard parameter will be false.

If your customer already has a saved card, there are 3 conditions that you may follow

• Your customer has a saved card but did not pass the OTP - sms verification (This means the customer did not see his/hre saved cards yet.)
  universalCardStorage: {registerConsumerCard: true, gsmNumber: "+905557378631", consumerToken: undefined, cardToken: undefined}
  If your form is submitted at this step, you can understand that your customer does not want to use a sotred card. You can check the object universalCardStorage. You can see that consumerToken and cardToken values in this object are undefined. So please process the payment with the form that you already use.

• The customer has a saved card and passed the OTP SMS verification (Customer sees the list of cards in the next screen )
  universalCardStorage: {registerConsumerCard: true, gsmNumber: "+905557378631", consumerToken: "31ad9-2335a3b", cardToken: "ca9c8360-ca08"}
  In this case, if customer submits the form, consumerToken and cardToken values are defined in universalCardStorage object. You can pass these values to your backend and use them in a payment request. This will provide you to get payments from saved cards. Instead of sending card information, passing consumerToken, cardToken and ucsToken information will be enough to use a saved card.(ucsToken value is available in UCS init response).

• Customer has saved cards, passes the OTP-SMS and wants to use a new card
  universalCardStorage: {registerConsumerCard: true, gsmNumber: "+905557378631", consumerToken: "31ad9-2335a3b", cardToken: undefined}
  As soon as the form is submitted, when you check universalCardStorage parameters, if consumerToken is True and the cardToken is undefined, this means that the customer wants to pay with a new card and save the card at the time of payment. You can continue with your payment form however you need to send one more parameter to save the card. If you send registerConsumerCard parameter as true, the card will be saved.

If Customer does not have a saved card

If the value of scriptType parameter in UCS service response is UCS_CONSENT then you can understand that your customer does not have a saved card in iyzico ecosystem. At the same time registerConsumerCard parameter in the universalCardStorage object will be received as False. At this step, if you want to save the card, you need to give information about aggreements and the customer should accept the aggreement. To do this, adding below "div" will be enough to show the agreement and informative text provided by iyzico.

You should also print javascript code coming from "script" parameter

Put mentioned "div" to the related area of your payment form

• <div id="ucs-cards"></div>

Your customer will see the screen below. If your customer checks the checkbox, registerConsumerCard parameter in universalCardStorage javascript object will become True. So as soon as your payment form is submitted, you can check this javascript value(universalCardStorage.registerConsumerCard). If it is True, this means that your customer confirmed the aggrement. So the card can be saved at the time of payment.

.

Not: Every UCSToken and universalCardStorage object is valid for 30 minutes. If they are not used within 30 minutes. you need to reinitate the UCS init request.

**Parameters to be sent to the service are as follows:

UCS init service**

Parameters to be returned from the service are as follows:

// create request class
$request = new \Iyzipay\Request\UCSInitializeRequest();
$request->setConversationId("1234566");
$request->setLocale("tr");
$request->setEmail("email@iyzico.com");
$request->setGsmNumber("+905557378631");

// make request
$result = \Iyzipay\Model\UCSInitialize::create($request,Config::options());

//Request
{
    "locale": "tr",
    "conversationId": "123456",    
    "email": "email@iyzico.com",
    "gsmNumber": "+905557378631"
}

//Response
{
  "buyerProtectedConsumer": false,
  "buyerProtectedMerchant": false,
  "gsmNumber": "+905533378631",
  "locale": "tr",
  "maskedGsmNumber": "+90********31",
  "merchantName": "Test Name - 58892",
  "script": "<script type=\"text/javascript\">if (typeof iyziUcsInit == 'undefined') {var iyziUcsInit = {\"baseUrl\":\"https://sandbox-api.iyzipay.com\", \"ucsToken\":\"32b30114-85dd-47a5-a2bd-9071c95bc389\",\"scriptType\":\"UCS_CONSENT\",\"buyerProtectedMerchant\":false,\"maskedGsmNumber\":\"+90********31\",\"gsmNumber\":\"+905533378631\",\"merchantName\":\"Sandbox Merchant Name - 58892\", createTag: function () {var iyziUcsJSTag = document.createElement('script'); iyziUcsJSTag.setAttribute('src', 'https://sandbox-static.iyzipay.com/checkoutform/v2/bundle.js?v=1575969451615'); document.head.appendChild(iyziUcsJSTag);}};if (typeof iyziInit == 'undefined') { iyziUcsInit.createTag(); }}</script>",
  "scriptType": "UCS_CONSENT",
  "status": "success",
  "systemTime": 1575969451615,
  "ucsToken": "32b30114-a2bd-9071c95bc389"
}

Sameple Codes

• Php

SENDING PAYMENT REQUEST WITH STORED CARD

Parameters to be sent to the service are as follows:

Response

Parameters to be returned from the service are as follows:

$request = new \Iyzipay\Request\CreatePaymentRequest();
$request->setLocale(\Iyzipay\Model\Locale::TR);
$request->setConversationId("123456789");
$request->setPrice("1");
$request->setPaidPrice("1.2");
$request->setCurrency(\Iyzipay\Model\Currency::TL);
$request->setInstallment(1);
$request->setBasketId("B67832");
$request->setPaymentChannel(\Iyzipay\Model\PaymentChannel::WEB);
$request->setPaymentGroup(\Iyzipay\Model\PaymentGroup::PRODUCT);
$paymentCard = new \Iyzipay\Model\PaymentCard();
$paymentCard->setUcsToken("sampleToken");
$paymentCard->setConsumerToken("55287-9000-00000-08");
$paymentCard->setCardToken("12332-3523-345-234-56456");
$request->setPaymentCard($paymentCard);
$buyer = new \Iyzipay\Model\Buyer();
$buyer->setId("BY789");
$buyer->setName("John");
$buyer->setSurname("Doe");
$buyer->setGsmNumber("+905350000000");
$buyer->setEmail("email@email.com");
$buyer->setIdentityNumber("74300864791");
$buyer->setLastLoginDate("2015-10-05 12:43:35");
$buyer->setRegistrationDate("2013-04-21 15:12:09");
$buyer->setRegistrationAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
$buyer->setIp("85.34.78.112");
$buyer->setCity("Istanbul");
$buyer->setCountry("Turkey");
$buyer->setZipCode("34732");
$request->setBuyer($buyer);
$shippingAddress = new \Iyzipay\Model\Address();
$shippingAddress->setContactName("Jane Doe");
$shippingAddress->setCity("Istanbul");
$shippingAddress->setCountry("Turkey");
$shippingAddress->setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
$shippingAddress->setZipCode("34742");
$request->setShippingAddress($shippingAddress);
$billingAddress = new \Iyzipay\Model\Address();
$billingAddress->setContactName("Jane Doe");
$billingAddress->setCity("Istanbul");
$billingAddress->setCountry("Turkey");
$billingAddress->setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
$billingAddress->setZipCode("34742");
$request->setBillingAddress($billingAddress);
$basketItems = array();
$firstBasketItem = new \Iyzipay\Model\BasketItem();
$firstBasketItem->setId("BI101");
$firstBasketItem->setName("Binocular");
$firstBasketItem->setCategory1("Collectibles");
$firstBasketItem->setCategory2("Accessories");
$firstBasketItem->setItemType(\Iyzipay\Model\BasketItemType::PHYSICAL);
$firstBasketItem->setPrice("0.3");
$basketItems[0] = $firstBasketItem;
$secondBasketItem = new \Iyzipay\Model\BasketItem();
$secondBasketItem->setId("BI102");
$secondBasketItem->setName("Game code");
$secondBasketItem->setCategory1("Game");
$secondBasketItem->setCategory2("Online Game Items");
$secondBasketItem->setItemType(\Iyzipay\Model\BasketItemType::VIRTUAL);
$secondBasketItem->setPrice("0.5");
$basketItems[1] = $secondBasketItem;
$thirdBasketItem = new \Iyzipay\Model\BasketItem();
$thirdBasketItem->setId("BI103");
$thirdBasketItem->setName("Usb");
$thirdBasketItem->setCategory1("Electronics");
$thirdBasketItem->setCategory2("Usb / Cable");
$thirdBasketItem->setItemType(\Iyzipay\Model\BasketItemType::PHYSICAL);
$thirdBasketItem->setPrice("0.2");
$basketItems[2] = $thirdBasketItem;
$request->setBasketItems($basketItems);

$payment = \Iyzipay\Model\Payment::create($request, Config::options());