OVO Wallet

Обзор

Введение

OVO Wallet — метод, позволяющий проводить платежи в индонезийских рупиях с использованием электронных кошельков в Индонезии. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты и выплаты. Для проведения оплат поддерживается использование двух каналов: без перенаправления пользователя к сервису провайдера (канал 1) и с перенаправлением пользователя (канал 2). Информацию о канале для проведения оплат необходимо уточнять у курирующего менеджера ecommpay.

В этой статье представлена информация о работе с методом OVO Wallet: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.

Характеристика

Тип платёжного метода платежи с использованием электронных кошельков
Платёжные инструменты электронные кошельки
Регионы использования ID
Валюты платежей IDR
Конвертация валют +
Разовые оплаты +
Повторяемые оплаты –
Полные возвраты –
Частичные возвраты –
Выплаты +
Опротестования –
Особенности при использовании этого метода все платежи в валюте IDR являются целочисленными. В запросах с указанием валюты IDR следует округлять суммы до целых чисел, иначе дробная часть отсекается при обработке платежа в платёжной платформе. При указании в запросах других валют сумма платежа конвертируется на стороне ecommpay с округлением до 1 000,00 IDR.
Организация и стоимость подключения по согласованию с курирующим менеджером ecommpay; дополнительную информацию можно получить в ecommpay shop

Схема работы

В проведении отдельного платежа с использованием метода OVO Wallet задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства сервиса провайдера.



Основные операции

Для проведения платежей и выполнения операций с использованием метода OVO Wallet могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок), а выплаты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения.

При работе с методом OVO Wallet, независимо от используемых интерфейсов, актуальны следующие свойства и ограничения.

Суммы ¹ Время ²
минимум максимум базовое предельное
Оплаты 10 000,00 2 000 000,00 до KYC*

10 000 000,00 после KYC

 1 минута 85 секунд
Выплаты 10 000,00 25 000 000,00 1 минута 45 дней
Прим.:
  1. KYC (Know Your Customer) — это процедура, которая позволяет финансовым организациям проверять клиентов, чтобы обезопасить себя от мошенников.
  2. Базовое и предельное время определяются следующим образом:
    • Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа (подробнее).
    • Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус decline. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.

Сценарии использования

Проведение оплат с использованием метода OVO Wallet осуществляется как с перенаправлением пользователей к сервису провайдера так и без него,проведение выплат — с уведомлением пользователей через веб-сервис мерчанта.

Рис. 1. Оплата через Payment Page без перенаправления пользователя
Рис. 2. Оплата через Payment Page с перенаправлением пользователя
Рис. 3. Оплата через Gate без перенаправления пользователя
Рис. 4. Оплата через Gate с перенаправлением пользователя
Рис. 5. Выплата через Gate

Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах. При использовании дополнительных возможностей (таких как платёжные ссылки) сценарии выполнения операций методом OVO Wallet соответствуют специфике этих возможностей.

Оплаты через Payment Page. Канал 1: без перенаправления пользователя

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

Для проведения оплаты через Payment Page с использованием метода OVO Wallet со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.



Рис. 6. Проведение оплаты через Payment Page. Описание шагов
  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
  5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
  6. Пользователю отображается платёжная форма.
  7. Пользователь выбирает для оплаты метод OVO Wallet.
  8. Пользователю отображается форма для ввода идентификатора учётной записи OVO.
  9. Пользователь указывает идентификатор.
  10. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода провайдера.
  11. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис провайдера.
  12. На стороне сервиса провайдера выполняется обработка запроса на оплату.
  13. От сервиса провайдера пользователю отправляется push-уведомление на мобильный телефон, на котором установлено приложение OVO.
  14. Пользователь выполняет необходимые действия в течение 70 секунд после получения уведомления.
  15. В сервисе провайдера выполняется обработка платежа.
  16. От сервиса OVO Wallet к платёжной платформе направляется информация о результате оплаты.
  17. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  18. От платёжной платформы к Payment Page направляется информация о результате оплаты.
  19. Информация о результате оплаты отображается пользователю на Payment Page

Информация о форматах запросов и оповещений, используемых для проведения оплат методом OVO Wallet через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.

Формат запросов

При формировании запросов на открытие платёжной формы с применением метода OVO Wallet необходимо учитывать следующее:

  1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
    • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
    • payment_amount — сумма платежа в дробных единицах валюты;
    • customer_id — идентификатор пользователя в рамках проекта.
  2. Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
  3. Дополнительно рекомендуется указывать идентификатор учётной записи OVO пользователя (должен содержать не более 15 цифр, без использования других символов) в параметре customer_account_number. Если параметр отсутствует в запросе, на Payment Page пользователю отображается поле для ввода недостающего значения. Подробнее об уточнении параметров — в разделе Дополнение информации о платежах.
  4. Для предварительного выбора метода OVO Wallet необходимо указывать код платёжного метода в параметре force_payment_method — ovo.
  5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
  6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

Таким образом, корректный запрос на открытие платёжной формы с применением метода OVO Wallet должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе и счёте, а также подпись.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "IDR",
   "customer_id": "customer1",
   "customer_account_number": "081211111111",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
Рис. 7. Пример достаточного набора данных для запроса на оплату
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "IDR",
   "customer_id": "customer1",
   "customer_account_number": "081211111111",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Формат оповещений

Для оповещений о результатах оплат с применением метода OVO Wallet используется типовой формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 439 была проведена оплата в размере 10 000,00 IDR.

Рис. 8. Пример данных из оповещения о проведении оплаты
{
        "project_id": 439,
        "payment": {
            "id": "EP8417-7f12",
            "type": "purchase",
            "status": "success",
            "date": "2021-06-09T13:41:43+0000",
            "method": "ovo",
            "sum": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "123"
        },
        "operation": {
            "id": 1711,
            "type": "sale",
            "status": "success",
            "date": "2021-06-09T13:41:43+0000",
            "created_date": "2021-06-09T13:41:39+0000",
            "request_id": "c66bf3ecb02c4c19a2c460712f2ed86f52-00000001",
            "sum_initial": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 6682,
                "payment_id": "",
                "auth_code": "",
                "date": "2021-06-09T13:41:42+0000"
            }
        },
        "signature": "ab51MI5wDVMOTwpwD2COA1m8ZXXDceGoTLIxAaiZihRQ=="
    }

В следующем примере оповещение свидетельствует об отклонённой оплате.

Рис. 9. Пример данных из оповещения об отклонении оплаты
{
        "project_id": 439,
        "payment": {
            "id": "EPe5bd-2f88",
            "type": "purchase",
            "status": "decline",
            "date": "2021-06-09T13:44:40+0000",
            "method": "ovo",
            "sum": {
                "amount": 20000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "9544544545"
        },
        "operation": {
            "id": 1712,
            "type": "sale",
            "status": "decline",
            "date": "2021-06-09T13:44:40+0000",
            "created_date": "2021-06-09T13:44:34+0000",
            "request_id": "2b4241e02c9e75156d60a78591da0b4ca1-00000001",
            "sum_initial": {
                "amount": 20000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 20000,
                "currency": "IDR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 6682,
                "payment_id": "",
                "auth_code": "",
                "date": "2021-06-09T13:44:38+0000"
            }
        },
        "signature": "aWYu87AYwbSFN9Yd+oUMsLEJk9rMwRaLaT1mPiP36Q=="
    }

Дополнительные материалы

Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:

Оплаты через Payment Page. Канал 2: с перенаправлением пользователя

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

Для проведения оплаты через Payment Page с использованием метода OVO Wallet со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.

Рис. 10. Проведение оплаты через Payment Page. Описание шагов
  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
  5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
  6. Пользователю отображается платёжная форма.
  7. Пользователь выбирает для оплаты метод OVO Wallet.
  8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода провайдера.
  9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис провайдера.
  10. В сервисе провайдера выполняется обработка запроса на оплату.
  11. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера.
  12. Данные для перенаправления пользователя передаются к Payment Page.
  13. Пользователь перенаправляется к сервису провайдера.
  14. Пользователь выполняет необходимые действия для оплаты.
  15. В сервисе провайдера выполняется обработка платежа.
  16. Информация о результате оплаты отображается пользователю в сервисе провайдера.
  17. Пользователь перенаправляется к Payment Page.
  18. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты.
  19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  20. От платёжной платформы к Payment Page направляется информация о результате оплаты.
  21. Информация о результате оплаты отображается пользователю на Payment Page.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом OVO Wallet через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.

Формат запросов

При формировании запросов на открытие платёжной формы с применением метода OVO Wallet необходимо учитывать следующее:

  1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
    • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
    • payment_amount — сумма платежа в дробных единицах валюты;
    • customer_id — идентификатор пользователя в рамках проекта.
  2. Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
  3. Дополнительно необходимо указывать имя и фамилию пользователя в параметрах customer_first_name и customer_last_name.
  4. Для предварительного выбора метода OVO Wallet необходимо указывать код этого метода в параметре force_payment_method — ovo.
  5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
  6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

Таким образом, корректный запрос на открытие платёжной формы с применением метода OVO Wallet должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе и подпись.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "IDR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_first_name": "Doe",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
Рис. 11. Пример достаточного набора данных для запроса на оплату
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "IDR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_first_name": "Doe",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Формат оповещений

Для оповещений о результатах оплат с применением метода OVO Wallet используется типовой формат, описание которого представлено в статье Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 439 была проведена оплата в размере 10 000,00 IDR.

Рис. 12. Пример данных из оповещения о проведении оплаты
{
        "project_id": 439,
        "payment": {
            "id": "EP8417-7f12",
            "type": "purchase",
            "status": "success",
            "date": "2021-06-09T13:41:43+0000",
            "method": "ovo",
            "sum": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "123"
        },
        "operation": {
            "id": 1711,
            "type": "sale",
            "status": "success",
            "date": "2021-06-09T13:41:43+0000",
            "created_date": "2021-06-09T13:41:39+0000",
            "request_id": "c66bf3ecb02c4c19a2c460712f2ed86f52-00000001",
            "sum_initial": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 6682,
                "payment_id": "",
                "auth_code": "",
                "date": "2021-06-09T13:41:42+0000"
            }
        },
        "signature": "ab51MI5wDVMOTwpwD2COA1m8ZXXDceGoTLIxAaiZihRQ=="
    }

В следующем примере оповещение свидетельствует об отклонённой оплате.

Рис. 13. Пример данных из оповещения об отклонении оплаты
{
        "project_id": 439,
        "payment": {
            "id": "EPe5bd-2f88",
            "type": "purchase",
            "status": "decline",
            "date": "2021-06-09T13:44:40+0000",
            "method": "ovo",
            "sum": {
                "amount": 20000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "9544544545"
        },
        "operation": {
            "id": 1712,
            "type": "sale",
            "status": "decline",
            "date": "2021-06-09T13:44:40+0000",
            "created_date": "2021-06-09T13:44:34+0000",
            "request_id": "2b4241e02c9e75156d60a78591da0b4ca1-00000001",
            "sum_initial": {
                "amount": 20000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 20000,
                "currency": "IDR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 6682,
                "payment_id": "",
                "auth_code": "",
                "date": "2021-06-09T13:44:38+0000"
            }
        },
        "signature": "aWYu87AYwbSFN9Yd+oUMsLEJk9rMwRaLaT1mPiP36Q=="
    }

Дополнительные материалы

Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:

Оплаты через Gate. Канал 1: без перенаправления пользователя

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

Для проведения оплаты через Gate с использованием метода OVO Wallet со стороны веб-сервиса необходимо:

  1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
  2. Принять итоговое оповещение от платёжной платформы.

Полная схема проведения оплаты выглядит следующим образом.



Рис. 14. Проведение оплаты через Gate. Описание шагов
  1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода OVO Wallet.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
  3. Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
  4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
  6. В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис провайдера.
  7. В сервисе провайдера выполняется обработка запроса на оплату.
  8. Со стороны провайдера пользователю отправляется push-уведомление на мобильный телефон, на котором установлено приложение OVO.
  9. Пользователь выполняет необходимые действия в течение 70 секунд после получения уведомления.
  10. В сервисе провайдера выполняется обработка платежа.
  11. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты.
  12. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  13. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом OVO Wallet через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Формат запросов

При работе с запросами на оплаты с применением метода OVO Wallet необходимо учитывать следующее:

  1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/ovo/sale. Эта точка относится к группе электронных кошельков /v2/payment/wallet/{payment_method}/sale.
  2. В каждом запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
      • payment_id — идентификатор платежа, уникальный в рамках проекта;,
      • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в дробных единицах валюты;,
      • currency — код валюты платежа в формате ISO-4217 alpha-3;,
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор пользователя, уникальный в рамках проекта;,
      • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;,
    • account — сведения об учётной записи пользователя:
      • number — идентификатор учётной записи OVO (должен содержать не более 15 цифр, без использования других символов).
  3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на оплату с применением метода OVO Wallet должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе и счёте, а также подпись.

{
    "general": {
        "project_id": 2373,
        "payment_id": "test123129",
        "signature": "6/E1dobuXL+JLua7pbgXm9QBqxv9JgM1EwBc3ovVQ=="
    },
    "payment": {
        "amount": 1000000,
        "currency": "IDR"
    },
    "account": {
        "number": "081211111111",
    },
    "customer": {
        "ip_address": "192.0.2.0",
        "id": "customer1"
    }
}
Рис. 15. Пример достаточного набора данных для запроса на оплату
{
    "general": {
        "project_id": 2373,
        "payment_id": "test123129",
        "signature": "6/E1dobuXL+JLua7pbgXm9QBqxv9JgM1EwBc3ovVQ=="
    },
    "payment": {
        "amount": 1000000,
        "currency": "IDR"
    },
    "account": {
        "number": "081211111111",
    },
    "customer": {
        "ip_address": "192.0.2.0",
        "id": "customer1"
    }
}

Формат итоговых оповещений

Для оповещений о результатах оплат с применением метода OVO Wallet используется типовой формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 439 была проведена оплата в размере 10 000,00 IDR.

Рис. 16. Пример данных из оповещения о проведении оплаты
{
        "project_id": 439,
        "payment": {
            "id": "EP8417-7f12",
            "type": "purchase",
            "status": "success",
            "date": "2021-06-09T13:41:43+0000",
            "method": "ovo",
            "sum": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "123"
        },
        "operation": {
            "id": 1711,
            "type": "sale",
            "status": "success",
            "date": "2021-06-09T13:41:43+0000",
            "created_date": "2021-06-09T13:41:39+0000",
            "request_id": "c66bf3ecb06e2c460712f2ed86f52-00000001",
            "sum_initial": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 6682,
                "payment_id": "",
                "auth_code": "",
                "date": "2021-06-09T13:41:42+0000"
            }
        },
        "signature": "ab51MI5wDVMO8jL/9wTwpwD2COA1m8ZXXDceGoTLIxAaiZihRQ=="
    }

В следующем примере оповещение свидетельствует об отклонённой оплате.

Рис. 17. Пример данных из оповещения об отклонении оплаты
{
        "project_id": 439,
        "payment": {
            "id": "EPe5bd-2f88",
            "type": "purchase",
            "status": "decline",
            "date": "2021-06-09T13:44:40+0000",
            "method": "ovo",
            "sum": {
                "amount": 20000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "9544544545"
        },
        "operation": {
            "id": 1712,
            "type": "sale",
            "status": "decline",
            "date": "2021-06-09T13:44:40+0000",
            "created_date": "2021-06-09T13:44:34+0000",
            "request_id": "2b4241e02c5e1e9e75156d60a78591da0b4ca1-00000001",
            "sum_initial": {
                "amount": 20000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 20000,
                "currency": "IDR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 6682,
                "payment_id": "",
                "auth_code": "",
                "date": "2021-06-09T13:44:38+0000"
            }
        },
        "signature": "aWYu87AYwBSFN9Yd+oUMsLEJk9rMwRaLaT1mPiP36Q=="
    }

Дополнительные материалы

Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:

Оплаты через Gate. Канал 2: с перенаправлением пользователя

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

Для проведения оплаты через Gate с использованием метода OVO Wallet со стороны веб-сервиса необходимо:

  1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
  2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису OVO Wallet.
  3. Принять итоговое оповещение от платёжной платформы.

Полная схема проведения оплаты выглядит следующим образом.

Рис. 18. Проведение оплаты через Gate. Описание шагов
  1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода OVO Wallet.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
  3. Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
  4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
  6. В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис провайдера.
  7. В сервисе провайдера выполняется обработка запроса на оплату.
  8. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера.
  9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису провайдера.
  10. Пользователь перенаправляется к сервису провайдера.
  11. Пользователь выполняет необходимые действия для оплаты.
  12. В сервисе провайдера выполняется обработка платежа.
  13. Пользователю отображается информация о результате оплаты.
  14. Пользователь перенаправляется к веб-сервису.
  15. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты.
  16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом OVO Wallet через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Формат запросов

При работе с запросами на оплаты с применением метода OVO Wallet необходимо учитывать следующее:

  1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/ovo/sale. Эта точка относится к группе электронных кошельков /v2/payment/wallet/{payment_method}/sale.
  2. В каждом запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
      • payment_id — идентификатор платежа, уникальный в рамках проекта;,
      • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в дробных единицах валюты;,
      • currency — код валюты платежа в формате ISO-4217 alpha-3;,
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор пользователя, уникальный в рамках проекта;,
      • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;,
      • first_name — имя пользователя,
      • last_name — фамилия пользователя;
    • return_url — объект, содержащий URL для перенаправления пользователя в веб-сервис:
      • return — URL для перенаправления пользователя любом шаге оплаты.
  3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на оплату с применением метода OVO Wallet должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, URL для перенаправления, а также подпись.

{
    "general": {
        "project_id": 2373,
        "payment_id": "test123129",
        "signature": "6/E1dobuXL+JLua7pbgXm9QBqxv9JgM1EwBc3ovVQ=="
    },
    "payment": {
        "amount": 1000000,
        "currency": "IDR"
    },
    "customer": {
        "ip_address": "192.0.2.0",
        "id": "customer1",
        "first_name": "John",
        "last_name": "Doe"
    },
    "return_url": {
        "return": "https://example.com/return"
    }
}
Рис. 19. Пример достаточного набора данных для запроса на оплату
{
    "general": {
        "project_id": 2373,
        "payment_id": "test123129",
        "signature": "6/E1dobuXL+JLua7pbgXm9QBqxv9JgM1EwBc3ovVQ=="
    },
    "payment": {
        "amount": 1000000,
        "currency": "IDR"
    },
    "customer": {
        "ip_address": "192.0.2.0",
        "id": "customer1",
        "first_name": "John",
        "last_name": "Doe"
    },
    "return_url": {
        "return": "https://example.com/return"
    }
}

Формат промежуточных оповещений для перенаправления пользователей

Для перенаправления пользователей от веб-сервиса мерчанта к сервису OVO Wallet при проведении каждого платежа с использованием метода OVO Wallet необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data включаются следующие объекты и параметры:

  • body — объект с данными для отправки в теле запроса;
  • method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
  • url — параметр со ссылкой для перенаправления.
Рис. 20. Пример объекта redirect_data
  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }

Формат итоговых оповещений

Для итоговых оповещений об оплатах с применением метода OVO Wallet используется типовой формат, описание которого представлено в статье Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 439 была проведена оплата в размере 10 000,00 IDR.

Рис. 21. Пример данных из оповещения о проведении оплаты
{
        "project_id": 439,
        "payment": {
            "id": "EP8417-7f12",
            "type": "purchase",
            "status": "success",
            "date": "2021-06-09T13:41:43+0000",
            "method": "ovo",
            "sum": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "123"
        },
        "operation": {
            "id": 1711,
            "type": "sale",
            "status": "success",
            "date": "2021-06-09T13:41:43+0000",
            "created_date": "2021-06-09T13:41:39+0000",
            "request_id": "c66bf3ecb06e2c460712f2ed86f52-00000001",
            "sum_initial": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 6682,
                "payment_id": "",
                "auth_code": "",
                "date": "2021-06-09T13:41:42+0000"
            }
        },
        "signature": "ab51MI5wDVMO8jL/9wTwpwD2COA1m8ZXXDceGoTLIxAaiZihRQ=="
    }

В следующем примере оповещение свидетельствует об отклонённой оплате.

Рис. 22. Пример данных из оповещения об отклонении оплаты
{
        "project_id": 439,
        "payment": {
            "id": "EPe5bd-2f88",
            "type": "purchase",
            "status": "decline",
            "date": "2021-06-09T13:44:40+0000",
            "method": "ovo",
            "sum": {
                "amount": 20000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "9544544545"
        },
        "operation": {
            "id": 1712,
            "type": "sale",
            "status": "decline",
            "date": "2021-06-09T13:44:40+0000",
            "created_date": "2021-06-09T13:44:34+0000",
            "request_id": "2b4241e02c5e1e9e75156d60a78591da0b4ca1-00000001",
            "sum_initial": {
                "amount": 20000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 20000,
                "currency": "IDR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 6682,
                "payment_id": "",
                "auth_code": "",
                "date": "2021-06-09T13:44:38+0000"
            }
        },
        "signature": "aWYu87AYwBSFN9Yd+oUMsLEJk9rMwRaLaT1mPiP36Q=="
    }

Дополнительные материалы

Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:

Выплаты через Gate

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

Для проведения выплаты через Gate с использованием метода OVO Wallet со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения выплаты выглядит следующим образом.



Рис. 23. Проведение выплаты через Gate
  1. Пользователь на стороне веб-сервиса инициирует выплату через OVO Wallet.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение выплаты через Gate.
  3. Запрос на проведение выплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
  6. В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис OVO Wallet.
  7. На стороне OVO Wallet выполняется обработка платежа.
  8. От OVO Wallet к платёжной платформе направляется оповещение о результате.
  9. От платёжной платформы к веб-сервису направляется оповещение о результате.
  10. От веб-сервиса пользователю направляется результат выплаты.

Информация о форматах запросов и оповещений, используемых для проведения выплат методом OVO Wallet через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Формат запросов

При работе с запросами на выплаты с применением метода OVO Wallet необходимо учитывать следующее:

  1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/ovo/payout. Эта точка относится к группе /v2/payment/wallet/{payment_method}/payout.
  2. В каждом запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
      • payment_id — идентификатор платежа, уникальный в рамках проекта;,
      • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
    • payment — сведения о платеже:
      • amount — сумма выплаты в дробных единицах валюты;,
      • currency — код валюты платежа в формате ISO-4217 alpha-3;,
    • customer — сведения о пользователе:
      • id — идентификатор пользователя, уникальный в рамках проекта;,
      • ip_address — IP-адрес пользователя, актуальный для инициируемой выплаты;,
    • account — сведения об учётной записи пользователя:
      • number — идентификатор учётной записи OVO (должен содержать не более 15 цифр, без использования других символов),
      • customer_name — полное имя пользователя.
  3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на выплату с применением метода OVO Wallet должен содержать идентификатор проекта, базовые сведения о платеже (его идентификатор, сумму и код валюты), информация о пользователе, номер счёта и подпись.

{
    "general": {
    "project_id": 2853,
    "payment_id": "test-002",
    "signature": "M1vT4q9c8hGFSAkn+aJmGA4jH6bgBOp8DTf8d/XdoV+vd7Q=="
  },
  "payment": {
    "amount": 10000,
    "currency": "IDR"
  },
  "customer": {
    "id": "payoutTest",
    "ip_address": "192.0.2.0"
  },
  "account": {
    "number": "081211111111",
     "customer_name": "John Doe"
  }
}
Рис. 24. Пример достаточного набора данных для запроса на оплату
{
    "general": {
    "project_id": 2853,
    "payment_id": "test-002",
    "signature": "M1vT4q9c8hGFSAkn+aJmGA4jH6bgBOp8DTf8d/XdoV+vd7Q=="
  },
  "payment": {
    "amount": 10000,
    "currency": "IDR"
  },
  "customer": {
    "id": "payoutTest",
    "ip_address": "192.0.2.0"
  },
  "account": {
    "number": "081211111111",
     "customer_name": "John Doe"
  }
}

Формат оповещений

Для оповещений о результатах выплат с применением метода OVO Wallet используется типовой формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 439 была проведена выплата в размере 10 000,00 IDR.

Рис. 25. Пример данных из оповещения о проведении выплаты
{
        "project_id": 439,
        "payment": {
            "id": "164601_32630630",
            "type": "payout",
            "status": "success",
            "date": "2021-06-09T13:46:08+0000",
            "method": "ovo",
            "sum": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "1234"
        },
        "customer": {
            "id": "customer1"
        },
        "operation": {
            "id": 1713,
            "type": "payout",
            "status": "success",
            "date": "2021-06-09T13:46:08+0000",
            "created_date": "2021-06-09T13:46:03+0000",
            "request_id": "5b164b90a7212ec90b6a9d528a-00000001",
            "sum_initial": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 1000000,
                "currency": "IDR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 6682,
                "payment_id": "ecf16ae5-6419",
                "auth_code": "",
                "date": "2021-06-09T13:46:06+0000"
            }
        },
        "signature": "upl29ym7t+r0aZ2SG+p3iVVEsoDnp+2YyQ=="
    }

В следующем примере оповещение свидетельствует об отклонённой выплате.

Рис. 26. Пример данных из оповещения об отклонении выплаты
{
        "project_id": 439,
        "payment": {
            "id": "164753_53114954",
            "type": "payout",
            "status": "decline",
            "date": "2021-06-09T13:48:00+0000",
            "method": "ovo",
            "sum": {
                "amount": 40000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "456"
        },
        "customer": {
            "id": "customer2"
        },
        "operation": {
            "id": 1714,
            "type": "payout",
            "status": "decline",
            "date": "2021-06-09T13:48:00+0000",
            "created_date": "2021-06-09T13:47:54+0000",
            "request_id": "2d61a590c269869b06bc48025f68-00000001",
            "sum_initial": {
                "amount": 40000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 40000,
                "currency": "IDR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 6682,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "WEXldjWeZaXmgxnALsxX/8UTQF7DkNPT0oQ=="
    }

Дополнительные материалы

Для организации работы с выплатами через Gate также могут быть полезны следующие материалы:

  • Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
  • Работа с подписью — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
  • Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
  • Выплаты — о том, как проводить выплаты через Gate.
  • Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.

Выплаты через Dashboard

При использовании интерфейса Dashboard можно проводить одиночные и массовые выплаты методом OVO Wallet с единичной и пакетной отправкой запросов, называемые соответственно одиночными и массовыми.

  • Для проведения одиночной выплаты необходимо открыть форму выплаты, задать все необходимые параметры (включая метод), отправить запрос и убедиться в проведении выплаты.

  • Для проведения массовой выплаты необходимо подготовить и загрузить файл с информацией обо всех целевых выплатах, отправить пакет запросов и убедиться в проведении выплат.

    При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе Сведения о массовых платежах, а параметры выплат — должны соответствовать требованиям, представленным в разделе Выплаты через Gate этой статьи (за исключением пункта о подписи).

Более подробная информация о проведении выплат через Dashboard представлена в отдельной статье.

Анализ результатов проведения платежей

Для анализа информации о платежах и операциях, как в отдельности по методу OVO Wallet, так и в совокупности с другими методами, можно использовать:

  • инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
  • отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
  • данные в формате JSON, получаемые по программным запросам через интерфейс Data API.

С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.