Google Pay™ - это мгновенный платежный способ от Google, который позволяет просто и быстро оплатить карточкой, без необходимости вводить платежные данные для каждого платежа. Данные карточки надежно хранятся в Google. Данный метод доступен для оплаты в мобильных приложениях на любых устройствах Android и при осуществлении платежа в браузере Chrome.
2.1 Подключение через страницу iPay
При таком способе подключения нет необходимости в дополнительных интеграциях. Кнопка Google Pay будет отображена на странице iPay.
2.2 Прямая интеграция через Google Pay API
2.2.1 Web интеграция
Чтобы подключить Google Pay к веб-сайту, действуйте в соответствии с инструкциями, размещенных по ссылкам:
Документация: https://developers.google.com/pay/api/web
Требования к брендированию: https://developers.google.com/pay/api/web/guides/brand-guidelines
2.2.2 Android интеграция
Чтобы подключить Google Pay к мобильному приложению, действуйте в соответствии с инструкциями, размещенных по ссылкам:
Документация: https://developers.google.com/pay/api/android
Требования к брендированию: https://developers.google.com/pay/api/android/guides/brand-guidelines
2.2.3 Настройки
Значения параметров, которые передаются в 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.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.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",
}
}
3.4.2 PaymentCreate
Структура тела запроса
Поле | Тип | Описание |
Обязательные поля | ||
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"
}
}
3.4.4 PaymentSale
Структура тела запроса
Поле | Тип | Описание |
Обязательные поля | ||
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"
}
}
3.4.5 PaymentCancel
Структура тела запроса
Поле | Тип | Описание |
Обязательные поля | ||
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": "АТ «Ощадбанк»"
}
}
3.4.6 StatusRequest
Структура тела запроса
Поле | Тип | Описание |
Обязательные поля | ||
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"
}
]
}
3.4.7 GetPaymentInvoice
Структура тела запроса
Поле | Тип | Описание |
Обязательные поля | ||
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 |