Перейти к основному содержимому

Masterpass™

Общая информация​

Masterpass — простой, удобный и надежный цифровой кошелек от Mastercard для более быстрых и безопасных покупок в интернет-магазинах. Все платежные детали хранятся в одном месте, а платить можно во всех магазинах, где принимается Masterpass, что позволяет клиенту избегать повторного ввода карточных данных, что значительно повышает конверсию.

Преимущества использования Masterpass:

  • Универсальность. Сервис работает с дебетовыми и кредитными картами платёжных систем MasterCard, Visa.
  • Безопасность. Многоуровневая система защиты практически исключает возможность кражи средств.
  • Удобство. Для клиента оплата проходит в один клик - нет необходимости повторно вводить номер и срок действия карты.
  • Оплаты по сохраненным в Masterpass картам будут приниматься во всех магазинах, где подключен данный сервис.

Клиент может сохранить до 5 карт для одного номера мобильного телефона, а также управлять ими через личный кабинет в Masterpass.

Важно

Данные плательщика не привязываются к мерчанту, т.е. сохранив карту один раз, в дальнейшем покупатель будет выбирать её из списка для оплаты во всех магазинах и приложениях, где есть Masterpass.

Интеграция по API​

Если у вас уже реализована интеграция по созданию плательщика, сохранению карт и оплате по сохраненным картам в ioka, то для интеграции Masterpass вам необходимо внести изменения по описанным ниже шагам в методы CreateCustomer и CreateCardPayment, а также запросить по почте support@ioka.kz подключение сервиса Masterpass к вашему магазину.

1. Создание плательщика​

Для проведения платежей по картам из Masterpass необходимо создать плательщика, используя метод CreateCustomer.

Важно

Для получения данных их Masterpass необходимо передать fingerprint, phone_check_date, channel

fingerprint (цифровой отпечаток устройства) — это уникальный идентификатор конфигураций мобильного устройства или браузера пользователя. Формирование fingerprint зависит от используемого устройства. При проведении платежей через web-браузер собирается Web Fingerprint, а при использовании мобильного приложения собирается Android/iOS Fingerprint. У одного плательщика может быть несколько fingerprint, в случае использования нескольких устройств или браузеров.

info

Для получения SDK (Web, Android, iOS) и подробной инструкции по формированию fingerprint необходимо написать на почту support@ioka.kz.

phone_check_date - дата последней успешной верификации номера телефона плательщика в системе мерчанта

channel - тип устройства плательщика (WEB, APP iOS или APP Android)

Пример запроса:

POST /v2/customers HTTP/1.1
Host: stage-api.ioka.kz
API-KEY: eyJ0eXAiOiJKV1..
Content-Type: application/json
{
    "email": "test@ioka.kz",
    "phone": "+77771112233",
    "fingerprint": "RGV2a...",
    "phone_check_date": "2022-01-01 09:00:00",
    "channel": "WEB"
}

Пример ответа:

{
    "customer":
        {
            "id": "string",
            "created_at": "string",
            "status": "PENDING",
            "external_id": "string",
            "email": "user@example.com",
            "phone": "string",
            "accounts": [
                {
                    "id": "string",
                    "shop_id": "string",
                    "customer_id": "string",
                    "status": "PENDING",
                    "name": "string",
                    "amount": "string",
                    "currency": "KZT",
                    "resources": [],
                    "created_at": "2019-08-24T14:15:22Z",
                    "external_id": "string"
                }
            ],
        "checkout_url": "http://example.com",
        "access_token": "string"
    },
    "customer_access_token": "string"
}

2. Получение и отображение карт плательщика​

Если по введенному номеру телефона у клиента были сохранены карты в Masterpass, то они автоматически будут доступны после создания плательщика. Для получения информации о сохраненных картах по customer_id воспользуйтесь методом GetCards.

Пример запроса:

GET /v2/customers/{{customer_id}}/cards HTTP/1.1
Host: stage-api.ioka.kz
API-KEY: eyJ0eXAiOiJKV1..

Пример ответа:

[
    {
        "id": "card_id",
        "customer_id": "customer_id",
        "created_at": "2023-02-14T06:35:16.689023",
        "pan_masked": "411111******1111",
        "expiry_date": "12/24",
        "holder": "HOLDER",
        "payment_system": "VISA",
        "emitter": "Bank",
        "cvc_required": true, 
        "masterpass_card": true,
        "error": null,
        "action": null
    },
    {
        "id": "card_id",
        "customer_id": "customer_id",
        "created_at": "2023-02-14T06:35:16.696876",
        "pan_masked": "5555******5599",
        "expiry_date": "12/24",
        "holder": "HOLDER",
        "payment_system": "MASTERCARD",
        "emitter": "Bank",
        "cvc_required": true,
        "masterpass_card": true,
        "error": null,
        "action": null
    }
]

3. Проведение оплаты по карте из Masterpass​

Вам необходимо:

Если выбранная карта была получена из хранилища Masterpass, то в ответе на запрос GetCards придет флаг "masterpass_card": true. В таком случае, в тело запроса CreateCardPayment необходимо передать card_id, fingerprint, phone_check_date, channel.

После успешной оплаты карта плательщика будет подтверждена и во все последующие запросы на CreateCardPayment необходимо передавать только card_id, т.е. параметры fingerprint, phone_check_date, channel собираются и передаются только при первой попытке оплаты.

Важно

При первой оплате по карте из Masterpass плательщику необходимо ввести CVC и, если на карте установлена 3D Secure проверка, пройти аутентификацию для подтверждения принадлежности карты её держателю.

Для этого необходимо перенаправить плательщика на action.url (ссылка на форму оплаты ioka с предзаполненным номером и сроком действия карты).

Пример запроса:

POST /v2/orders/{{order_id}}/payments/card HTTP/1.1
Host: stage-api.ioka.kz
API-KEY: eyJ0eXAiOiJKV1..
Content-Type: application/json
{
    "card_id": "card_id",
    "fingerprint": "RGV2a...",
    "phone_check_date": "2022-01-01 09:00:00",
    "channel": "WEB"
}

Пример ответа:

{
    "id": "pay_test",
    "order_id": "ord_test",
    "status": "REQUIRES_ACTION",
    "created_at": "2023-02-14T06:36:22.511992",
    "approved_amount": 0,
    "captured_amount": 0,
    "refunded_amount": 0,
    "processing_fee": 0.0,
    "tds": false,
    "payer": null,
    "acquirer": null,
    "error": null,
    "action": {
        "url": "https://test.ioka.kz/orders/ord_w8qkzciAjI"
    }
}

4. Проверка статуса платежа​

Доступны несколько способов для проверки статуса платежа:

  1. Настроить получение уведомлений (webhook-ов) от ioka на события PAYMENT_APPROVED, PAYMENT_CAPTURED, PAYMENT_DECLINED.
  2. Периодически запрашивать информацию о заказе методом GetOrderByID.
  3. Проверять статус в Личном Кабинете Мерчанта.

В случае успешной оплаты карта плательщика будет подтверждена и card_id будет доступен для проведения платежей по сохраненной карте.