KakaoPay
Обзор
Введение
KakaoPay — метод, позволяющий проводить платежи в южнокорейских вонах с использованием электронного кошелька в Республике Корея. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты и возвраты.
В этой статье представлена информация о работе с методом KakaoPay: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.
Характеристика
Тип платёжного метода | платежи с использованием электронных кошельков |
---|---|
Платёжные инструменты | электронные кошельки |
Регионы использования | KR |
Валюты платежей | KRW |
Конвертация валют | – |
Разовые оплаты | + |
Повторяемые оплаты | – |
Полные возвраты | + |
Частичные возвраты | + |
Выплаты | – |
Опротестования | – |
Особенности | для платежей с использованием валюты KRW не используются дробные единицы |
Организация и стоимость подключения | по согласованию с курирующим менеджером ecommpay |
Схема работы
В проведении отдельного платежа с использованием KakaoPay задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ecommpay, а также технические средства сервиса KakaoPay.
Основные операции
Для проведения платежей и выполнения операций с использованием метода KakaoPay могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page и Gate, а возвраты — через Gate и Dashboard.
Сценарии использования
Проведение оплат с использованием метода KakaoPay осуществляется с отображением пользователям платёжной инструкции, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса мерчанта.
Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах. При использовании дополнительных возможностей (таких как платёжные ссылки) сценарии выполнения операций методом KakaoPay соответствуют специфике этих возможностей.
Оплаты через Payment Page
Общая информация
Для проведения оплаты через Payment Page с использованием метода KakaoPay со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом KakaoPay через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.
Формат запросов
При формировании запросов на открытие платёжной формы с применением метода KakaoPay необходимо учитывать следующее:
- Должен использоваться базовый минимум параметров, обязательный для любого платежа:
project_id
— идентификатор проекта, полученный от ecommpay при интеграции;payment_id
— идентификатор платежа, уникальный в рамках проекта;payment_currency
— код валюты платежа в формате ISO-4217 alpha-3;payment_amount
— сумма платежа без выделения дробной части, посколько при работе с валютой KRW дробные единицы не используются;customer_id
— идентификатор пользователя в рамках проекта.
- Должен использоваться базовый минимум параметров:
project_id
,payment_id
,payment_currency
,payment_amount
,customer_id
. - Валютой платежа может быть только KRW.
- Для предварительного выбора метода KakaoPay необходимо указывать код этого метода в параметре
force_payment_method
—kakaopay-wallet
. - Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
- После указания всех целевых параметров необходимо составлять подпись (подробнее).
Таким образом, корректный запрос на открытие платёжной формы с применением метода KakaoPay должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор пользователя и подпись.
Формат оповещений
Для оповещений о результатах оплат с применением метода KakaoPay используется типовой формат, описание которого представлено в статье Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 1234
для пользователя customer1
была проведена оплата в размере 1000 KRW
.
В следующем примере оповещение свидетельствует об отклонённой оплате.
Дополнительные материалы
Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
- Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Payment Page.
- Информация о выполнении операций — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.
Оплаты через Gate
Общая информация
Для проведения оплаты через Gate с использованием метода KakaoPay со стороны веб-сервиса необходимо:
- Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
- Принять промежуточное оповещение с данными для отображения платёжной инструкции и отобразить пользователю эту инструкцию.
- Принять итоговое оповещение от платёжной платформы.
Полная схема проведения оплаты выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для проведения оплат методом KakaoPay через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При работе с запросами на оплаты с применением метода KakaoPay необходимо учитывать следующее:
- Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/wallet/kakaopay/sale
, которая относится к группе конечных точек /v2/payment/wallet/{payment_method}/sale. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, уникальный в рамках проекта;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
payment
— объект, содержащий сведения о платеже:amount
— сумма платежа без выделения дробной части, поскольку при работе с валютой KRW дробные единицы не используются;,currency
— код валюты платежа в формате ISO-4217 alpha-3;,
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя, уникальный в рамках проекта;,ip_address
— IP-адрес пользователя, актуальный для инициируемого платежа;,
return_url
— объект, содержащий URL для перенаправления пользователя в веб-сервис:success
— URL для перенаправления в случае проведённого платежа;,decline
— URL для перенаправления в случае отклонённого платежа;,return
— URL для возврата пользователя в веб-сервис мерчанта во время или после оплаты.
- Валютой платежа может быть только KRW.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на оплату с применением метода KakaoPay должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, подпись, а также URL для перенаправления пользователя в веб-сервис мерчанта.
Формат промежуточных оповещений для отображения платёжной инструкции
Для отображения пользователям платёжной инструкции при проведении каждого платежа с использованием метода KakaoPay необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в массив display_data
. Формат таких оповещений является типовым (подробнее), при этом в состав массива display_data
включаются следующие параметры:
type
— тип передаваемых данных (в значении всегда передаётсяqr_img
);title
— название передаваемых данных, которые необходимо отобразить пользователю (в значении всегда передаётсяQR code
);data
— строка, на основании которой на стороне веб-сервиса должен быть создан QR-код (в соответствии со стандартом ISO/IEC 18004:2015).
Формат итоговых оповещений
Для итоговых оповещений об оплатах с применением метода KakaoPay используется типовой формат, описание которого представлено в статье Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 1234
для пользователя customer1
была проведена оплата в размере 1000 KRW
.
В следующем примере оповещение свидетельствует об отклонённой оплате.
Дополнительные материалы
Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Возвраты через Gate
Общая информация
Для выполнения возврата через Gate с использованием метода KakaoPay со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема выполнения возврата выглядит следующим образом.
Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом KakaoPay через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.
Формат запросов
При работе с запросами на возвраты с применением метода KakaoPay необходимо учитывать следующее:
- Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке
/v2/payment/wallet/kakaopay/refund
, которая относится к группе конечных точек /v2/payment/wallet/{payment_method}/refund. - В каждом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;,payment_id
— идентификатор платежа, для которого необходимо выполнить возврат;,signature
— подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее)),
payment
— объект, содержащий сведения о возврате:description
— комментарий к возврату или его описание;,amount
— сумма возврата (без выделения дробной части, поскольку при работе с валютой KRW дробные единицы не используются; является обязательной при частичном возврате);,currency
— код валюты возврата в формате ISO-4217 alpha-3 (является обязательным при частичном возврате).
- Валютой возврата может быть только KRW.
- Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.
Таким образом, корректный запрос на возврат с применением метода KakaoPay должен содержать идентификаторы проекта и платежа, описание возврата, подпись, а также, при необходимости, код валюты и сумму возврата.
Формат оповещений
Для оповещений о результатах возвратов с применением метода KakaoPay используется типовой формат, описание которого представлено в разделе Оповещения.
В следующем примере оповещение свидетельствует о том, что в рамках проекта 1234
для пользователя customer1
был выполнен возврат в размере 1000 KRW
.
В следующем примере оповещение свидетельствует об отклонённом возврате.
Дополнительные материалы
Для организации работы с возвратами через Gate также могут быть полезны следующие материалы:
- Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
- Работа с подписью — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
- Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
- Возвраты средств после оплат — о том, как выполнять возвраты через Gate.
- Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.
Возвраты через Dashboard
При использовании интерфейса Dashboard можно выполнять одиночные и массовые возвраты методом KakaoPay с единичной и пакетной отправкой запросов, называемые соответственно одиночными и массовыми.
- Для выполнения одиночного возврата необходимо выбрать целевую оплату, открыть карточку этой оплаты, указать сумму возврата, отправить запрос и убедиться в выполнении возврата.
-
Для выполнения массового возврата необходимо подготовить и загрузить файл с информацией обо всех целевых возвратах, отправить пакет запросов и убедиться в выполнении возвратов.
При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе Сведения о массовых платежах, а параметры возвратов — требованиям, представленным в разделе Возвраты через Gate этой статьи (за исключением пункта о подписи).
Более подробная информацияИнформация о выполнении возвратов через Dashboard представлена в отдельном разделе.
Анализ результатов проведения платежей
Для анализа информации о платежах и операциях, как в отдельности по методу KakaoPay, так и в совокупности с другими методами, можно использовать:
- инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
- отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
- данные в формате JSON, получаемые по программным запросам через интерфейс Data API.
С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.