Документация iPay Google Pay API

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

Google Pay™ - это мгновенный платежный способ от Google, который позволяет просто и быстро оплатить карточкой, без необходимости вводить платежные данные для каждого платежа. Данные карточки надежно хранятся в Google. Данный метод доступен для оплаты в мобильных приложениях на любых устройствах Android и при осуществлении платежа в браузере Chrome.

2. Интеграция

2.1 Подключение через страницу iPay

При таком способе подключения нет необходимости в дополнительных интеграциях. Кнопка Google Pay будет отображена на странице iPay.

2.2 Прямая интеграция через Google Pay API

Чтобы подключить Google Pay к веб-сайту, действуйте в соответствии с инструкциями, размещенных по ссылкам:

Документация: https://developers.google.com/pay/api/web

Требования к брендированию: https://developers.google.com/pay/api/web/guides/brand-guidelines

Чтобы подключить Google Pay к мобильному приложению, действуйте в соответствии с инструкциями, размещенных по ссылкам:

Документация: https://developers.google.com/pay/api/android

Требования к брендированию: https://developers.google.com/pay/api/android/guides/brand-guidelines

Значения параметров, которые передаются в PaymentMethod объекте:

allowedAuthMethods = ["PAN_ONLY", "CRYPTOGRAM_3DS"];
allowedCardNetworks = ['MASTERCARD', 'VISA'];
tokenizationSpecification.type = "PAYMENT_GATEWAY";
tokenizationSpecification.parameters.gateway = "ipayua";
tokenizationSpecification.parameters.gatewayMerchantId = "YOUR_IPAY_MERCHANT_ID".

3. Проведение платежа

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

Для взаимодействия с iPay Google Pay API следует получить идентификатор мерчанта (login) и ключ для подписи (sign key).

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

Формат передачи данных: JSON методом POST

Кодировка: UTF-8

Алгоритм подписи (поле sign в запросе):
Нужно объединить следующие строки в одну: время запроса (поле request.auth.time) и ключ для подписи, и зашифровать алгоритмом SHA3-512.

Создание и подтверждение платежа

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

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

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

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

При выполнении запроса PaymentCreate на карте клиента блокируется сумма, которая передана в запросе, в ответе возвращается статус платежа = 3.

После запроса PaymentCreate нужно обязательно завершить оплату запросом PaymentSale. Если в запросе PaymentSale значение поля invoice меньше, чем было в запросе PaymentCreate, разница возвращается на карту пользователю. При успешном завершении запроса в ответе возвращается статус платежа = 5.

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

Google Pay доступен в тестовой среде, установите значение "TEST" для свойства "environment" объекта PaymentOptions.

Тестовые платежи выполняются без списания с карты.

3D Secure включен для платежа на сумму более 500 грн.

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

Поле Тип Описание
request object Объект запроса
request.auth object Объект аутентификации
request.auth.login string ID мерчанта
request.auth.time string Время запроса в часовом поясе Europe/Kiev
Формат: YYYY-MM-DD HH:MM:SS
Пример: 2017-01-01 00:00:00
request.auth.sign string Подпись запроса
request.action string Название запроса
request.body object Объект тела запроса

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "token": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHDJCIn0= ...",
            "pmt_desc": "Test payment ",
            "pmt_info": {
                "custom_merchant_field": 1234567
            },
            "guid": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}
                  

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

3.4.1 CalculateFee

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

Поле Тип Описание
Обязательные поля
invoice integer Сумма платежа, в копейках

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "CalculateFee",
        "body": {
            "invoice": 100
        }
    }
}

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

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

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

{
    "response": {
        "invoice":"1000",
        "amount":"1100",
        "fee":"100",
    }
}

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

Поле Тип Описание
Обязательные поля
invoice integer Сумма платежа, в копейках
token string Токен GooglePay в формате JSON закодированный в Base64
pmt_desc string Описание платежа
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_color_depth 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
Опциональные поля
msisdn string Номер телефона
guid string Идентификатор запроса, сформированный мерчантом
transactions array Массив транзакций. Позволяет разделить платеж на несколько получателей средств.
transactions[].invoice integer Сумма платежа, в копейках
transactions[].smch_id integer ID получателя средств, предоставляется iPay
transactions[].desc integer Назначение платежа (в формате текст до 100 знаков)
transactions[].info object Дополнительная информация о платеже

Пример запроса (один получатель средств)

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "token": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHDJCIn0= ...",
            "pmt_desc": "Test payment",
            "pmt_info": {
                "custom_merchant_field": 1234567
            },
            "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"
            },
            "guid": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}

Пример запроса (несколько получателей средств)

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00dc94b74a7cfdced473 ..."
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "invoice": 100,
            "token": "eyJwYXltZW50RGF0YSI6eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiZ3ZNWHDJCIn0= ...",
            "transactions": [
                {"invoice":50,"smch_id":"5410","desc":"Тестовий платіж","info":{"custom_field_1":"test"}},
                {"invoice":50,"smch_id":"5472","desc":"Тестовий платіж","info":{"custom_field_1":"test"}}
            ]
            "guid": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}

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

Поле Тип Описание
response object Объект ответа
response.pmt_id integer ID платежа в системе iPay
response.invoice integer Сумма платежа, в копейках
response.amount integer Сумма к оплате (с учетом комиссии), в копейках
response.pmt_status integer Статус платежа (1 - требуется верификация платежа, 3 - предавторизация средств успешна (только для двухстадийного платежа), 4 - ошибка платежа, 5 - успешное списание, 14 - отказ службы безопасности)
response.card_mask string Маска карты
response.bank_response object Ответ банка
response.bank_response.error_group integer Группа ошибки
response.bank_acquirer_name string Название банка эквайера
response.rrn string RRN (возвращается для статуса платежа - 3, 5)
response.auth_code string Код авторизации (возвращается для статуса платежа - 3, 5)
В случае успешного платежа (pmt_status = 5) дополнительно возвращаются следующие поля
response.mch_amount array Данные о зачислениях Торговцу
response.mch_amount[].smch_id string Внутренний идентификатор юридического лица
response.mch_amount[].amount string Сумма зачисления в копейках
Дополнительные поля при верификации платежа
response.security_rate string Тип верификации платежа (3D)
response.security_data.redirect_url string URL для перенаправления пользователя

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

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 5,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "rrn": "021705522966",
        "auth_code": "040280"
    }
}

Пример ответа (3D Secure)

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 1,
        "security_rate": "3D",
        "security_data": {
            "redirect_url": "https://example.com/acs"
        },
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»"
    }
}

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

3.4.3 PaymentVerify3DS

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

Поле Тип Описание
Обязательные поля
pmt_id integer ID платежа в системе iPay
threeds_data string Результат прохождения 3D Secure верификации
Опциональные поля
guid string Идентификатор запроса, сформированный мерчантом

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentVerify3DS",
        "body": {
            "pmt_id": 1234567,
            "threeds_data": "eJxlUttygjAQ\/RXHDzAJIoKzZgbr1MEp3mBa7UsnQkZRucjFol...",
            "guid": "e55f613987964042a92bfc2d4f0d610d"
        }
    }
}

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

Поле Тип Описание
response object Объект ответа
response.pmt_id integer ID платежа в системе iPay
response.invoice integer Сумма платежа, в копейках
response.amount integer Сумма к оплате (с учетом комиссии), в копейках
response.pmt_status integer Статус платежа (3 - предавторизация средств успешна, 4 - ошибка платежа, 5 - успешное списание)
response.card_mask string Маска карты
response.bank_response object Ответ банка
response.bank_response.error_group integer Группа ошибки
response.bank_acquirer_name string Название банка эквайера
response.rrn string RRN (возвращается для статуса платежа - 3, 5)
response.auth_code string Код авторизации (возвращается для статуса платежа - 3, 5)
В случае успешного платежа (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": 100,
        "pmt_status": 5,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "rrn": "021705522966",
        "auth_code": "040280"
    }
}

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

Поле Тип Описание
Обязательные поля
pmt_id integer ID платежа в системе iPay
invoice integer Финальная сумма платежа, в копейках
Опциональные поля
guid string Идентификатор запроса, сформированный мерчантом

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentSale",
        "body": {
            "pmt_id": 1234567,
            "invoice": 100,
            "guid": "e55f613987964042a92bfc2d4f0d610d"
        }
    }
}

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

Поле Тип Описание
response object Объект ответа
response.pmt_id integer ID платежа в системе iPay
response.invoice integer Сумма платежа, в копейках
response.amount integer Сумма к оплате (с учетом комиссии), в копейках
response.pmt_status integer Статус платежа (4 - ошибка платежа, 5 - успешное списание)
response.card_mask string Маска карты
response.bank_response object Ответ банка
response.bank_response.error_group integer Группа ошибки
response.bank_acquirer_name string Название банка эквайера
response.rrn string RRN (возвращается для статуса платежа - 3, 5)
response.auth_code string Код авторизации (возвращается для статуса платежа - 3, 5)
В случае успешного платежа (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": 100,
        "pmt_status": 4,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": 12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»",
        "rrn": "021705522966",
        "auth_code": "040280"
    }
}

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

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

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2018-07-09 03:40:37",
            "sign": "a12a4d5eb7da121bc04d360a5c11fd7be246817f7ac1845b17eb00 ..."
        },
        "action": "PaymentCancel",
        "body": {
            "pmt_id": 1234567
        }
    }
}

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

Поле Тип Описание
response object Объект ответа
response.pmt_id integer ID платежа в системе iPay
response.invoice integer Сумма платежа, в копейках
response.amount integer Сумма к оплате (с учетом комиссии), в копейках
response.pmt_status integer Статус платежа (4 - ошибка платежа, 9 - успешно отменен)
response.card_mask string Маска карты
response.bank_response object Ответ банка
response.bank_response.error_group integer Группа ошибки
response.bank_acquirer_name string Название банка эквайера

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

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 9,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": null
        },
        "bank_acquirer_name": "АТ «Ощадбанк»"
    }
}

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

Поле Тип Описание
Обязательные поля
guid string Идентификатор запроса мерчанта, что был передан в предыдущих запросах

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2019-02-19 10:47:35",
            "sign": "a468afe066f57e08d2b36dd74c03218f3701b17aba8fa15ebea..."
        },
        "action": "StatusRequest",
        "body": {
            "guid": "AD68E7675FE111E79A65005056B960DFF"
        }
    }
}

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

Поле Тип Описание
response array Тело ответа
response[].action string Назва запиту
response[].msisdn string Номер телефону, 12 digits long (e.g. 380931234567)
response[].response string Ответ в формат JSON
response[].date string Дата запиту

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

{
    "response": [
        {
            "action": "PaymentCreate",
            "msisdn": "380931234567",
            "response": "{\"response\":{\"pmt_id\":\"1234567\",\"invoice\":\"20000\",\"amount\":\"20000\",\"pmt_status\":\"5\",\"card_alias\":\"Test\",\"card_mask\":\"111111********11\",\"msisdn\":\"380931234567\",\"bank_response\":{\"bank_id\":\"31\",\"rc\":\"000\",\"action\":\"\",\"error_group\":null}}}",
            "date": "2017-01-01 15:47:27"
        }
    ]
}

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

Поле Тип Описание
Обязательные поля
pmt_id integer ID платежа в системе iPay

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

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2019-02-19 10:47:35",
            "sign": "a468afe066f57e08d2b36dd74c03218f3701b17aba8fa15ebea..."
        },
        "action": "GetPaymentInvoice",
        "body": {
            "pmt_id": 1234567
        }
    }
}

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

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

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

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

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

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

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

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

{
    "response": {
        "error": "invalid request structure"
    }
}
Название ошибки Описание
overall error Общая ошибка
invalid request structure Неправильная структура запроса
invalid action Неизвестный тип запроса
invalid token Не удалось расшифровать токен
invalid token format Токен должен быть в формате JSON
invalid token gatewayMerchantId Неизвестное значение gatewayMerchantId
unknown field {field_name} Неизвестное поле
invalid pan Неверный формат PAN карты
invalid expm Неверный формат месяца срока действия карты
invalid expy Неверный формат года срока действия карты
invalid cvv Неверный формат CVV
invalid auth Ошибка аутентификации
invalid auth time Неверный формат времени запроса
access denied Доступ запрещен

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

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

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

{
    "response": {
        "pmt_id": 1234567,
        "invoice": 100,
        "amount": 100,
        "pmt_status": 4,
        "card_mask": "111111******1111",
        "bank_response": {
            "error_group": 12
        },
        "bank_acquirer_name": "АТ «Ощадбанк»"
    }
}
Группа ошибки Описание
41 Отказ банка эмитента
42 Недостаточно средств
43 Лимит банка эмитента
50 Неверный CVV код
51 Ошибка прохождения 3D Secure
52 Ошибка связи с банком
55 Неизвестная ошибка
56 Срок действия карты закончился
57 Неверный номер карты
58 Лимит на карте
60 Ошибка прохождения 3D Secure