iPay masterpass API v1.7.7

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

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

Решение masterpass, которое описано в данной документации позволяет значительно упростить оплату клиентом товаров и услуг через Интернет.

Кошелек masterpass имеет следующие параметры:

  1. Имя клиента - это мобильный номер в формате +380 ХХ ХХХ ХХ ХХ.
  2. Номера карт - в кошельке можно хранить до 5-и различных карт.

Логика взаимодействия Торговца с кошельком masterpass следующая. На сайте Торговца должна быть авторизованная зона, личный кабинет. Логином или обязательным параметром должен быть номер телефона клиента. ВАЖНО! Номер телефона не может быть изменен пользователем без дополнительной верификации (подтверждения, что именно он является владельцем этого телефона. Лучше всего, это сделать через одноразовый смс-код).

Когда клиент находится в Личном кабинете Торговца и оплачивает с помощью кошелька masterpass клиенту необходимо предложить одно из следующих действий:

  1. Если у клиента есть кошелек masterpass, тогда предложить его подключить (залинковать) в личный кабинет. Процесс линковки значит, что клиент доверяет данному Торговцу инициировать запросы на авторизацию по его кошельку.
  2. Если у клиента есть кошелек и он уже залинкован (привязан к Торговцу), тогда клиенту необходимо показать карточки, которые в зарегистрированы в его кошельке.
  3. Если у клиента нет кошелька, тогда предложить зарегистрировать первую карточку для более удобных расчетов.
    (все описанные выше пути происходят на стороне iPay.ua при переадресации клиента на определенный URL)

На сайте Торговца необходимо реализовать меню для управления картами в кошельке masterpass (добавление, удаление карточек). Следует понимать, что кошелек masterpass, это глобальный кошелек. Когда клиент добавляет в него карточку или удаляет, она добавляется/удаляется в глобальной базе данных, то есть для всех Торговцев, с которыми клиент залинковал свой кошелек.

После того, как клиент зарегистрировался в Личном кабинете Торговца и подключил (залинковал) свой кошелек, пользователь может произвести оплату с помощью одной из карточек, выбрав ее из списка. При этом Торговец НЕ перенаправляет клиента на страницу сервис-провайдера или эквайера для ввода карточных данных. Все происходит на стороне Торговца и в один клик. С помощью специального метода происходит списание средств с карты.

При этом для обеспечения безопасности платежа, компания iPay.ua может настроить проверку одноразового пароля через смс (OTP_SMS). То есть для осуществления операции на телефон клиента, зарегистрированного в masterpass, придет смс с 6-значным кодом. Этот код клиент должен ввести на сайте Торговца для подтверждения. Данный механизм подтверждения клиента настраивается на операции выше определенной суммы.

Доступы и настройки

Для взаимодействия следует получить следующие значения:

- login - идентификатор Торговца
- sign key - ключ для подписи

URL адрес для запросов - https://walletmc.ipay.ua/

Формат передачи - JSON методом POST

Кодирока сообщений - UTF-8

Алгоритм подписи (поле sign в запросе):
Требуется объединить две строки в одну: "время запроса" (поле time в запросе) и "ключ для подписи". Результат зашифровать алгоритмом SHA-512.

Например:
Поле time в запросе равно "2017-01-01 00:00:00", sign key равен "12347b6ac566d63de29becf2a7e148ef".
Выполняем объединение двух строк в одну: "2017-01-01 00:00:0012347b6ac566d63de29becf2a7e148ef" и шифруем алгоритмом SHA-512, полученный результат шифрования - "b0e540ef2db2505a8a646513785b5e370ad3958430934fe584f89a5e8b17e6d347ad43c763eb34736f4389b73fffc9a3303c3c25aa0081832dfd9a48f2e5a46d" будет значением поля sign в запросе.

Порядок выполнения запросов

Блок схема

diagram

Диаграмма последовательности

sequense

Процедура добавления карты в кошелек

Перед добавлением НОВОЙ карты, нужно выполнить запрос на проверку существования номера телефона в программе masterpass (запрос Check).

Возможны 2 варианта ответа:
- notexists - нет активного аккаунта masterpass;
- invite - номер телефона уже зарегистрирован в masterpass и имеет привязанные карты.

В случае ответа notexists нужно:
Выполнить запрос RegisterByURL и получить URL формы регистрации, по которому переадресовать клиента.
Регистрация имеет такие шаги:
- вводятся карточные данные и название карты;
- происходит OTP верификация владельца телефона (приходит смс с кодом, который нужно ввести на форме регистрации)
- происходит LOOKUP верификация карты (на карте блокируется сумма 1 грн, значение кода авторизации необходимо ввести на форме регистрации).

В случае ответа invite нужно:

Вариант 1: Выполнить запрос InviteByURL и получить URL формы регистрации, по которому переадресовать клиента.
- происходит LOOKUP верификация карточки которая уже зарегистрирована в masterpass (на карточке блокируется сумма 1 грн, значение кода авторизации надо ввести на форме регистрации).

Вариант 2: Выполнить запрос Invite в ответ поступит token, который нужно запомнить для выполнения следующего запроса.
На телефон в смс будет отправлен LOOKUP код зарегистрированной карты в masterpass, который передается в запрос "Otp".

Для добавления ДОПОЛНИТЕЛЬНОЙ карты нужно:
Выполнить запрос AddcardByURL и получить URL формы регистрации, по которому переадресовать клиента.
Регистрация дополнительной карты имеет следующие шаги:
- вводятся карточные данные и название карты;
- происходит LOOKUP верификация карты (на карточке блокируется сумма 1 грн, значение кода авторизации необходимо ввести на форме регистрации).

Процедура создания и подтверждения платежа

Тип платежа (одностадийный или двухстадийный) настраивается на стороне iPay.

Одностадийный платеж

Для оплаты требуется выполнить один запрос - PaymentCreate, с банковской карты клиента списывается сумма переданная в запросе.

Двухстадийный платеж

При выполнении запроса PaymentCreate на банковской карте клиента блокируется сумма переданная в запросе.

После запроса PaymentCreate обязательно требуется завершить оплату вызовом запроса PaymentSale.

При выполнении запроса PaymentSale выполняется окончательное списание суммы, если поле invoice отличается от переданного ранее на запрос PaymentCreate, разница будет возвращена на банковскую карту пользователя (частичная отмена).

Общая структура запроса

Структура запросов отличается полями action (название запроса) и body (тело запроса).

Поле Тип Описание
request object Объект запроса
request.auth object Объект аутентификации
request.auth.login string Идентификатор Торговца
request.auth.time string Время запроса (часовой пояс - Europe/Kiev)
request.auth.sign string Подпись запроса
request.action string Название запроса
request.body object Объект тела запроса

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "Check",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500"
        }
    }
}

Перечень запросов

  1. List (Список доступных карт)

    2. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "List",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500"
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.{card_alias}.card_alias string Название карты, которую выбирает клиент
    response.{card_alias}.mask string Маска карты (первые 6 и 2 последние цифры номера карты)
    response.{card_alias}.uid string Уникальный идентификатор карты
    response.{card_alias}.is_expired integer 0 - карта активна
    1 - срок действия карты закончился
    response.{card_alias}.is_corporate integer 0 - не корпоративная карта
    1 - корпоративная карта

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

    {
    "response": {
        "TEST_CARD": {
            "card_alias": "TEST_CARD",
            "mask": "111122********44",
            "uid": "1B149F911665EBD54331CC3E7DD1BA5496F8F77590455A61511A190231B0FEC6",
            "is_expired": 0,
            "is_corporate": 0
        },
        "TEST_CARD_2": {
            "card_alias": "TEST_CARD_2",
            "mask": "111122********44",
            "uid": "5B149F911665EBD54331CC3E7DD1BA5496F8F77590455A61511A190231B0FEC6",
            "is_expired": 1,
            "is_corporate": 1
        }
    }
}

  2. Check (Проверить клиента)

    3. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "Check",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500"
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.user_status string Статус пользователя. Может принимать следующие значения:

    - notexists - пользователь незарегистрирован;
    - exists - пользователь зарегистрирован и у него есть карты;
    - invite - пользователь зарегистрирован, но требует подтверждения на пользование картами;
    - blocked - masterpass кошелек заблокирован.

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

    {
    "response": {
        "user_status": "notexists"
    }
}

  3. Invite (Пригласить клиента)

    4. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "Invite",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500"
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.verify string Требуется пройти верификацию MPin
    response.token string Временное уникальное значение токена (требует сохранения для завершения операции), строка длиной 192 символа

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

    {
    "response": {
        "verify": "mpin",
        "token": "ED7461B42BDAFC0554EC6452436C84151FC38A52D1C7B1CED19915A1911B3620BC4B6CB16F15EBF ..."
    }
}

  4. UnlinkUser (Отвязать пользователя от Торговца)

    5. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "UnlinkUser",
        "body": {
            "msisdn": "380931234567"
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.status string Статус запроса: success или error

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

    {
    "response": {
        "status": "success"
    }
}

  5. InviteByURL (Пригласить клиента через web интерфейс)

    6. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов
    lang string Язык интерфейса, может принимать одно из следующих значений: ua | ru | en
    Опциональные поля
    success_url string Ссылка на страницу Торговца после успешного запроса
    error_url string Ссылка на страницу Торговца после неуспешного запроса

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "InviteByURL",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru",
            "success_url": "http://localhost/success",
            "error_url": "http://localhost/error"
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.url string Ссылка на страницу Торговца куда нужно перенаправить клиента для подключения существующего кошелька

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

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ru/partner/link"
    }
}

  6. RegisterByURL (Регистрация кошелька с добавлением первой карты через web интерфейс)

    7. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов
    lang string Язык интерфейса, может принимать одно из следующих значений: ua | ru | en
    Опциональные поля
    success_url string Ссылка на страницу Торговца после успешного запроса
    error_url string Ссылка на страницу Торговца после неуспешного запроса

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "RegisterByURL",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru",
            "success_url": "http://localhost/success",
            "error_url": "http://localhost/error"
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.url string Ссылка на страницу Торговца куда нужно перенаправить клиента для регистрации кошелька и добавления карты

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

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ru/partner/example/register?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R"
    }
}

  7. RegisterPurchaseByURL (Регистрация кошелька с добавлением первой карты и оплатой через web интерфейс)

    8. Если пользователь успешно оплатил услугу, Торговцу будет отправлена нотификация методом POST в формате XML. Документация по нотификации предоставляется отдельно.

    Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов
    lang string Язык интерфейса, может принимать одно из следующих значений: ua | ru | en
    success_url string Ссылка на страницу Торговца после успешного запроса
    error_url string Ссылка на страницу Торговца после неуспешного запроса
    invoice integer Сумма платежа, в копейках
    pmt_desc string Назначание платежа, предоставляется Торговцем при создании платежа (в формате текст до 100 знаков)
    pmt_info object Информация к платежу, предоставляется Торговцем при создании платежа

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "RegisterPurchaseByURL",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru",
            "success_url": "http://localhost/success",
            "error_url": "http://localhost/error",
            "invoice": 100,
            "pmt_desc": "Оплата за услугу: Интернет; Номер договора: 1234567; Сумма: 100.00 грн.",
            "pmt_info": {
                "custom_field_1": 1234567,
                "custom_field_2": 100
            }
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.url string Ссылка на страницу куда нужно перенаправить клиента для добавления карты и оплаты

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

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ru/partner/example/registerpurchase?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R"
    }
}

  8. AddcardByURL (Добавить карту в существующий кошелек через web интерфейс)

    9. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов
    lang string Язык интерфейса, может принимать одно из следующих значений: ua | ru | en
    Опциональные поля
    success_url string Ссылка на страницу Торговца после успешного запроса
    error_url string Ссылка на страницу Торговца после неуспешного запроса

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "AddcardByURL",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru",
            "success_url": "http://localhost/success",
            "error_url": "http://localhost/error"
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.url string Ссылка на страницу куда нужно перенаправить клиента для добавления карты

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

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ru/partner/example/addcard?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R"
    }
}

  9. Otp (Провести верификацию карты или платежа с помощью одноразового пароля)

    10. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов
    token string Временное уникальное значение токена (требует сохранения для завершения операции), строка длиной 192 символа
    value string Проверочный код

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

     
{
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "Otp",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "token": "ED7461B42BDAFC0554EC6452436C84151FC38A52D1C7B1CED19915A1911B3620BC4B6CB16F15EBF252D0D85C531C0 ...",
            "value": "625348"
        }
    }
}

    Верификация карты

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.status string Статус операции, может принимать одно из двух значений: "OK" или "FAIL"

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

    {
    "response": {
        "status": "OK"
    }
}

    Верификация платежа

    Структура ответа

    Показателем того, что платеж был успешно подтвержден является статус 5 (одностадийный платеж) или статус 1 (двухстадийный платеж) в ответе на запрос.

    Поле Тип Описание
    response object Тело ответа
    response.pmt_id string Номер платежа в системе iPay
    response.invoice string Сумма платежа, в копейках
    response.amount string Сумма к оплате (с учетом комиссии), в копейках
    response.pmt_status string Статус платежа (1 - зарегистрирован, 4 - неуспешный, 5 - успешный)
    response.card_alias string Название карты, которую выбирает клиент
    response.card_mask string Маска карты (первые 6 и 2 последние цифры номера карты)
    response.msisdn string Номер телефона, длина 12 (например 380931234567)
    response.bank_response object Ответ банка
    response.bank_response.bank_id string ID банка
    response.bank_response.trm_id string Терминал
    response.bank_response.error_group string Группа ошибки

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

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "5",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}

  10. DeleteCard (Удалить карту)

    11. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов
    card_alias string Название карты, которую нужно удалить из кошелька

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "DeleteCard",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "card_alias": "TEST"
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.status string Статус операции, может принимать одно из двух значений: "OK" или "FAIL"

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

    {
    "response": {
        "status": "OK"
    }
}

  11. CalcPaymentAmount (Рассчитать сумму к оплате с учетом комиссии)

    12. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов
    invoice integer Сумма платежа, в копейках

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "CalcPaymentAmount",
        "body": {
            "msisdn": "380931234567",
            "user_id": "750200",
            "invoice": 100
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.invoice integer Сумма платежа, в копейках
    response.amount integer Сумма к оплате (с учетом комиссии), в копейках

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

    {
    "response": {
        "invoice": 100,
        "amount": 102
    }
}

  12. PaymentCreate (Создать платеж)

    13. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов
    invoice integer Сумма платежа, в копейках
    card_alias string Название карты, которую выбирает клиент
    pmt_desc string Назначание платежа, предоставляется Торговцем при создании платежа (в формате текст до 100 знаков)
    pmt_info object Информация к платежу, предоставляется Торговцем при создании платежа
    threeds_info object Данные для 3D Secure верификации
    threeds_info.notification_url string URL, на который будет отправлен результат прохождения 3D Secure верификации
    threeds_info.threeds_requestor_url string Адрес сайта, на котором выполняется оплата
    threeds_info.browser_language string Язык браузера пользователя согласно стандарта IETF BCP 47, например "en-US"
    threeds_info.browser_screen_height string Высота экрана пользователя в пикселях
    threeds_info.browser_screen_width string Ширина экрана пользователя в пикселях
    threeds_info.browser_accept_header string Точное значение HTTP заголовков, отправленных из браузера пользователя на сайт, на котором выполняется оплата
    threeds_info.browser_tz string Смещение часового пояса между Гринвичем и местным временем пользователя, в минутах, например "-120" для часового пояса Europe/Kiev
    threeds_info.browser_user_agent string Точное значение HTTP заголовка user-agent
    threeds_info.user_ip string IP адрес пользователя
    Опціональні поля
    ext_id string ID платежа в системе Торговца, строка до 50 символов (буквы (A-Za–z), цифры (0–9), символы (-))
    transactions array Массив транзакций. Позволяет разделить платеж между несколькими получателями.
    transactions[].invoice integer Сумма, в копейках
    transactions[].smch_id integer ID получателя средств, предоставляется iPay
    transactions[].desc integer Назначание платежа, предоставляется Торговцем при создании платежа (в формате текст до 100 знаков)
    transactions[].info object Информация к платежу, предоставляется Торговцем при создании платежа

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "invoice": 100,
            "card_alias": "TEST",
            "pmt_desc": "Оплата за услугу: Интернет; Номер договора: 1234567; Сумма: 100.00 грн.",
            "pmt_info": {
                "custom_field_1": 1234567,
                "custom_field_2": 100
            },
            "threeds_info":{
                "notification_url": "https://www.merchantsite.com/notification",
                "threeds_requestor_url": "https://www.merchantsite.com",
                "browser_color_depth": "24",
                "browser_language": "en-US",
                "browser_screen_height": "1920",
                "browser_screen_width": "1080",
                "browser_tz": "-120",
                "browser_accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9",
                "browser_user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.66 Safari/537.36",
                "user_ip": "192.168.0.1"
            }
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.pmt_id string Номер платежа в системе iPay
    response.invoice string Сумма платежа, в копейках
    response.amount string Сумма к оплате (с учетом комиссии), в копейках
    response.pmt_status string Статус платежа (0 - требуется верификация платежа, 1 - зарегистрирован, 4 - неуспешный, 5 - успешный)
    response.card_alias string Название карты, которую выбирает клиент
    response.card_mask string Маска карты (первые 6 и 2 последние цифры номера карты)
    response.msisdn string Номер телефона, длина 12 (например 380931234567)
    response.rrn string Поле возвращается для статуса платежа - 1, 5
    response.auth_code string Код авторизации. Поле возвращается для статуса платежа - 1, 5
    response.bank_response object Ответ банка
    response.bank_response.bank_id string ID банка
    response.bank_response.trm_id string Терминал
    response.bank_response.error_group string Группа ошибки
    Если требуется верификация платежа дополнительно возвращаются следующие поля
    response.security_rate string Тип верификации платежа, может принимать одно из следующих значений:
    - "2D" (OTP верификация)
    - "3D" (3DS верификация)
    OTP верификация
    response.security_data.token string Временное уникальное значение токена (требует сохранения для завершения операции), строка длиной 192 символа
    3DS верификация
    response.security_data.redirect_url string URL на который нужно перенаправить пользователя для прохождения 3D Secure верификации
    В случае успешного платежа (pmt_status = 5) дополнительно возвращаются следующие поля
    response.mch_amount array Данные о зачислениях Торговцу
    response.mch_amount[].smch_id string Внутренний идентификатор юридического лица
    response.mch_amount[].amount string Сумма зачисления в копейках

    Пример ответа (без верификации)

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": "100",
        "amount": "102",
        "pmt_status": "9",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}
    Пример ответа (OTP верификация) 
    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "9",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        },
        "security_rate": "2D",
        "security_data": {
            "token" : "ED7461B42BDAFC0554EC6452436C84151FC38A52D1C7B1CED19915A1911B3620BC4B6CB16F15EBF ..."    
        }
    }
}

    В случае OTP верификации владельцу карты на мобильный телефон было отправлено смс сообщение с кодом. Этот код и token который был возвращен в запросе надо передать в запрос "Otp", если верификация прошла успешно средства на счета клиенту будут списаны или заблокированы в зависимости от типа платежа - одностадийный или двухстадийный.

    Пример ответа (3DS верификация) 
    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "9",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        },
        "security_rate": "3D",
        "security_data": {
            "redirect_url": "https://example.com/acs"
        }
    }
}

    В случае 3D Secure верификации нужно перенаправить пользователя по URL, указанный в поле security_data.redirect_url.
    После прохождения верификации пользователем, результат проверки будет отправлено POST методом на threeds_info.notification_url указанный в запросе "PaymentCreate", результат проверки содержит следующее поле: threedsData, значение этого поля нужно отправить на запрос "PaymentVerify3DS", если верификация прошла успешно средства на карте клиента будут списаны или заблокированы в зависимости от типа платежа - одностадийный или двухстадийний.

  13. PaymentVerify3DS (Провести 3DS верификацию платежа)

    14. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов
    pmt_id integer Номер платежа в системе iPay
    threeds_data string Результат прохождения 3DS верификации

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentVerify3DS",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "pmt_id": "1234567",
            "threeds_data": "eJxlUttygjAQ\/RXHDzAJIoKzZgbr1MEp3mBa7UsnQkZRucjFol\/fhFKlbV5y9uTs7kk24O5TzscO ..."
        }
    }
}

    Структура ответа

    Показателем того, что платеж был успешно подтвержден является статус 5 (одностадийный платеж) или статус 1 (двухстадийный платеж) в ответе на запрос.

    Поле Тип Описание
    response object Тело ответа
    response.pmt_id string Номер платежа в системе iPay
    response.invoice string Сумма платежа, в копейках
    response.amount string Сумма к оплате (с учетом комиссии), в копейках
    response.pmt_status string Статус платежа (1 - зарегистрирован, 4 - неуспешный, 5 - успешный)
    response.card_alias string Название карты, которую выбирает клиент
    response.card_mask string Маска карты (первые 6 и 2 последние цифры номера карты)
    response.msisdn string Номер телефона, длина 12 (например 380931234567)
    response.rrn string Поле возвращается для статуса платежа - 1, 5
    response.auth_code string Код авторизации. Поле возвращается для статуса платежа - 1, 5
    response.bank_response object Ответ банка
    response.bank_response.bank_id string ID банка
    response.bank_response.trm_id string Терминал
    response.bank_response.error_group string Группа ошибки
    В случае успешного платежа (pmt_status = 5) дополнительно возвращаются следующие поля
    response.mch_amount array Данные о зачислениях Торговцу
    response.mch_amount[].smch_id string Внутренний идентификатор юридического лица
    response.mch_amount[].amount string Сумма зачисления в копейках

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

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "1",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}

  14. PaymentSale (Выполнить платеж)

    15. Запрос выполняется только в том случае, если это двухстадийный платеж.

    Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    pmt_id integer Номер платежа в системе iPay
    invoice integer Окончательная сумма покупки в копейках

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentSale",
        "body": {
            "pmt_id": "1234567",
            "invoice": 100
        }
    }
}

    Структура ответа

    Показателем того, что платеж был успешно подтвержден является статус платежа 5 в ответе на запрос.

    Поле Тип Описание
    response object Тело ответа
    response.pmt_id string Номер платежа в системе iPay
    response.invoice string Сумма платежа, в копейках
    response.amount string Сумма к оплате (с учетом комиссии), в копейках
    response.pmt_status string Статус платежа (1 - зарегистрирован, 4 - неуспешный, 5 - успешный)
    response.card_alias string Название карты, которую выбирает клиент
    response.card_mask string Маска карты (первые 6 и 2 последние цифры номера карты)
    response.msisdn string Номер телефона, длина 12 (например 380931234567)
    response.rrn string Поле возвращается для статуса платежа - 1, 5
    response.auth_code string Код авторизации. Поле возвращается для статуса платежа - 1, 5
    response.bank_response object Ответ банка
    response.bank_response.bank_id string ID банка
    response.bank_response.trm_id string Терминал
    response.bank_response.error_group string Группа ошибки
    В случае успешного платежа (pmt_status = 5) дополнительно возвращаются следующие поля
    response.mch_amount array Данные о зачислениях Торговцу
    response.mch_amount[].smch_id string Внутренний идентификатор юридического лица
    response.mch_amount[].amount string Сумма зачисления в копейках

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

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "5",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}

  15. PaymentCancel (Отменить платеж)

    16. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    pmt_id integer Номер платежа в системе iPay
    Опциональные поля
    amount integer Сума частичного возврата, в копейках

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentCancel",
        "body": {
            "pmt_id": "1234567"
        }
    }
}

    Структура ответа

    Показателем того, что платеж был успешно отменен является статус 9 в ответе на запрос.

    Поле Тип Описание
    response object Тело ответа
    response.pmt_id string Номер платежа в системе iPay
    response.invoice string Сумма платежа, в копейках
    response.amount string Сумма к оплате (с учетом комиссии), в копейках
    response.pmt_status string Статус платежа (1 - зарегистрирован, 4 - неуспешный, 5 - успешный, 9 - отменен)
    response.card_alias string Название карты, которую выбирает клиент
    response.card_mask string Маска карты (первые 6 и 2 последние цифры номера карты)
    response.msisdn string Номер телефона, длина 12 (например 380931234567)
    response.bank_response object Ответ банка
    response.bank_response.bank_id string ID банка
    response.bank_response.trm_id string Терминал
    response.error_group string Группа ошибки

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

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "9",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}

  16. GetPaymentInvoice (Запросить квитанцию)

    17. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов
    pmt_id integer Номер платежа в системе iPay

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "GetPaymentInvoice",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "pmt_id": "1234567"
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.invoice string Ссылка на квитанцию

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

    {
    "response": {
        "invoice": "https://example.com/invoice/23d53e29722d2b03c954718c1d54b53787985090"
    }
}

  17. GetPaymentStatus (Статус платежа)

    18. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    ext_id string Идентификатор запроса Торговца, что был передан на запрос PaymentCreate

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "GetPaymentStatus",
        "body": {
            "ext_id": "123456"
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response object Тело ответа
    response.pmt_id string Номер платежа в системе iPay
    response.invoice string Сумма платежа, в копейках
    response.amount string Сумма к оплате (с учетом комиссии), в копейках
    response.pmt_status string Статус платежа (1 - зарегистрирован, 4 - неуспешный, 5 - успешный)
    response.card_alias string Название карты, которую выбирает клиент
    response.card_mask string Маска карты (первые 6 и 2 последние цифры номера карты)
    response.msisdn string Номер телефона, длина 12 (например 380931234567)
    response.rrn string Поле возвращается для статуса платежа - 1, 5
    response.auth_code string Код авторизации. Поле возвращается для статуса платежа - 1, 5
    response.bank_response object Ответ банка
    response.bank_response.bank_id string ID банка
    response.bank_response.trm_id string Терминал
    response.bank_response.error_group string Группа ошибки
    В случае успешного платежа (pmt_status = 5) дополнительно возвращаются следующие поля
    response.mch_amount array Данные о зачислениях Торговцу
    response.mch_amount[].smch_id string Внутренний идентификатор юридического лица
    response.mch_amount[].amount string Сумма зачисления в копейках

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

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "9",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}

  18. GetBankList (Получить список банков)

    19. Структура тела запроса

    Тело запроса (request.body) передается пустым объектом.

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "GetBankList",
        "body": {}
    }
}

    Структура ответа

    Поле Тип Опис
    response array Тело ответа
    response.[].id integer ID банка
    response.[].name string Название банка

    Приклад відповіді

    {
   "response": [
      {
         "id":28,
         "name":"Ощадбанк"
      },
      {
         "id":29,
         "name":"Приватбанк"
      },
      {
         "id":31,
         "name":"Райффайзен банк Аваль"
      },
      {
         "id":41,
         "name":"Ідея Банк"
      },
      {
         "id":49,
         "name":"Конкорд Банк"
      },
      {
         "id":99,
         "name":"Банк Січ"
      }
   ]
}

  19. InitWidgetSession (Инициирование сессии виджета)

    20. Структура тела запроса

    Поле Тип Описание
    Обязательные поля
    msisdn string Номер телефона, длина 12 цифр (например 380931234567)
    user_id string Внутренний идентификатор пользователя Торговца, разрешаются буквы, дефис, цифры, длина до 45 символов
    pmt_desc string Назначание платежа, предоставляется Торговцем при создании платежа (в формате текст до 100 знаков)
    pmt_info object Информация к платежу, предоставляется Торговцем при создании платежа
    pmt_info.invoice integer Сумма платежа в копейках

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

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "InitWidgetSession",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "pmt_desc": "Оплата за услугу: Интернет; Номер договора: 1234567; Сумма: 100.00 грн.",
            "pmt_info": {
                "invoice": 100
            }
        }
    }
}

    Структура ответа

    Поле Тип Описание
    response array Тело ответа
    response[].session string Идентификатор сессии

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

    {
    "response": {
        "session": "487fcwbg7xafbT3R652mc8c2794r7l5C"
    }
}

Тестовая среда

В тестовой среде верификация платежей включена от 5 грн. (500 копеек), если сумма меньше платеж будет проведен без верификации.

OTP пароль при OTP верификации платежа является статическим: 471771

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

Код для верификации номера телефона или карты является статическим: 111111

Для тестирования подключения кошелька в тестовой среде, создайте кошелек (добавьте первую карточку) и выполните запрос UnlinkUser, на запрос Check будет возвращаться user_status = invite.

Номер картки CVC2/CVV2 Срок дії Опис
5506900140100107 [Any] [Any] Успішний платіж, 3DS верифікація
5506900140100206 [Any] [Any] Неуспішний платіж, 3DS верифікація
5204740009900048 [Any] [Any] Успішний платіж, OTP верифікація
5204740009900055 [Any] [Any] Неуспішний платіж, OTP верифікація

Системные ошибки

Структура ответа

Поле Тип Описание
response object Тело ответа
response.error string Название ошибки

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

{
    "response": {
        "error": "invalid request structure"
    }
}

Перечень возможных ошибок

Ошибка Описание
overall error Общая ошибка
invalid request structure Неправильная структура запроса
user validation failed Ошибка валидации поля "user_id". Данный номер телефона уже привязкн к другому пользователю в личном кабинете Торговца.
unknown field {field_name} В запросе передано поле, которое неизвестно системе
invalid expm Неправильное значение expm
invalid expy Неправильное значение expy
invalid cvv Неправильное значение cvv
invalid value Неправильное значение value
invalid pan Неправильное значение pan
invalid auth Ошибка аутентификации
invalid auth time Неправильное время запроса
access denied Доступ запрещен
invalid msisdn Неправильное значение msisdn
invalid clientIp Неправильное значение clientIp
card is expired Срок действия карты закончился
no card Карта не найдена
try again later Пожалуйста, попробуйте повторить запрос позже

Группы ошибок

Если при выполнении запросов PaymentCreate, Otp, PaymentVerify3DS, PaymentSale получен статус 4, в объекте bank_response поле error_group содержит группу ошибки банка.

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

{
    "response": {
        "pmt_id": "1234567",
        "invoice": "100",
        "amount": "102",
        "pmt_status": "4",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "error_group": "42",
            "bank_id": 28,
            "trm_id": 123456
        }
    }
}

Перечень групп ошибок

Группа ошибки Описание
41 Отказ банка. Пожалуйста, проверьте, что на карте достаточно средств и не превышен лимит на проведение операций через Интернет.
42 Отказ банка, недостаточно средств для проведения операции.
43 Отказ банка, превышен лимит суммы сделки. Пожалуйста, свяжитесь с Вашим банком, чтобы увеличить лимит на проведение операций через Интернет.
50 Неправильный CVV код. Попробуйте ещё раз.
51 Ошибка 3D Secure верификации. Попробуйте ещё раз.
52 Ошибка соединения, повторите попытку позже.
55 Во время обработки платежа произошла ошибка.

Список банков

ID банка Название
28 Ощадбанк
29 Приватбанк
31 Райффайзен Банк Аваль
41 Идея Банк
49 Конкорд банк
99 Банк Сич

Подключение виджета masterpass

1. Требуется выполнить запрос InitWidgetSession, в ответе вернется идентификатор сессии, который будет актуален в течение 30 минут.
2. Разместить на странице код вызова виджета. Пример страницы с подключенным виджетом:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta content="width=device-width, initial-scale=1.0" name="viewport">
    <title>iPay masterpass widget</title>
    <script type="text/javascript" src="https://widgetmp.ipay.ua/widget.js"></script>
</head>
<body>
<a href="#" onclick="MasterpassWidget.open(
            {
                partner: 'test',
                lang: 'ru', 
                session: '123fcwbg7xafbT3R652mc4c2794r7l5C'
            },
            // функция, которая будет выполнена после закрытия виджета
            function() {},
            // функция, которая будет выполнена после успешной оплаты
            function() {},
            // функция, которая будет выполнена после оплаты с ошибкой
            function() {}
);">
</a>
</body>
</html>
В метод MasterpassWidget.open требуется передать объект со следующими параметрами:
- partner - идентификатор Торговца (login);
- lang - язык интерфейса ( ru | ua);
- session - идентификатор сессии полученный на запрос InitWidgetSession.

Если пользователь успешно оплатил услугу, Торговцу будет отправлена нотификация методом POST в формате XML. Документация по нотификации предоставляется отдельно.

История изменений

Дата Версия Описание
2016-09-14 1.1 Настройка запросов PaymentCreate, PaymentSale.
2016-12-02 1.2 Настройка запросов RegisterByURL, DeleteCard.
2016-12-12 1.3 Настройка запроса InviteByURL.
2017-02-13 1.4 Добавлены блок схема и диаграмма последовательности.

Методы PaymentStatus, PaymentCancel исключен из прод. среды в связи с модификацией.
2017-02-17 1.4.1 Добавлено поле сумма в запросе PaymentSale и возможность частичной отмены после списания.
2017-02-21 1.4.2 Исправление ошибок документации в разделе "Процедура создания и подтверждения платежа" и запросе PaymentSale.
2017-02-22 1.5 Добавлен запрос PaymentCancel (Отменить платеж).
2017-02-24 1.6 Добавлен запрос StatusRequest (Статус запроса).

Изменен запрос PaymentCancel: добавлен обязательный параметр msisdn, для получения корректного ответа на запрос StatusRequest.
2017-03-06 1.6.1 Добавлен опциональный параметр "guid", по которому можно проверять статус запроса.
2017-03-10 1.6.2 Запрос Invite возвращен в документацию.
2017-03-15 1.6.5 Добавлен метод AddcardByURL - добавление карты к существующему кошельку.
2017-03-22 1.6.7 Обновлен раздел "Общая информация".
2017-04-11 1.6.8 Обновлены запросы PaymentCreate, PaymentSale, PaymentCancel: к ответу добавлено поле bank_response.

Добавлен раздел "Коды ошибок банка".
2017-05-16 1.6.9 Обновлен запрос PaymentCreate: добавлена верификация платеда OTP, 3DS.

Добавлен новый банк-еквайер Приватбанк.
2017-06-02 1.7.0 В запросы AddcardByURL, InviteByURL та RegisterByURL добавлены дополнительные поля success_url, error_url
(ссылки на страницу Торговца после успешного и неуспешного запроса)
2017-06-15 1.7.1 Добавлены следующие запросы:
- CalcPaymentAmount (рассчитать сумму к оплате (с учетом комиссии))
- TestInvite (тестирование приглашения клиента)
2017-06-22 1.7.2 К каждому запросу добавлено поле user_id (внутренний идентификатор пользователя Торговца)
2017-07-03 1.7.3 Добавлен запрос RegisterPurchaseByURL (Регистрация кошелька с добавлением первой карта и оплатой через web интерфейс)
2017-07-13 1.7.4 Добавлен одностадийный платеж.
2017-07-24 1.7.5 Добавлено поле is_expired (срок действия карты закончился или нет) в ответе на запрос List.
2017-09-11 1.7.6 Добавлен новый банк-эквайер Райффайзен Банк Аваль.

Добавлено поле is_corporate (карта корпоративная или нет) в ответе на запрос List.
2022-06-02 1.7.7 Добавлен новый запрос GetBankList.