- Регистрация и конфигурация платежного модуля
- Статусы инвойсов
- Типовые схемы работы с платежными системами
- Создание оплаты
- Подтверждение оплаты
- Отмена оплаты
- Возврат
- Обновление данных инвойса
- Проверка данных инвойса
Работа с API производится в соответствии с правилами работы с API. Для интеграции используются API-методы секции Платежи.
Для интеграции необходимо:
USERЗапросить у пользователя API-ключ для доступа к системеAPIЗарегистрировать новый интеграционный платежный модульUSERПроизвести необходимые настройки на странице настройки интеграции в платежном модулеUSERСоздать типы оплаты, связанные с магазинами созданного платежного модуляSYSTEMЗапросы связанные с оплатами будет инициировать система в процессе работы пользователяAPIОтправлять в CRM систему актуальную информацию по платежам
Этапы с пометкой USER — это этапы, выполняемые пользователем. Этапы с пометкой API выполняются посредством API-запросов от платежного модуля к CRM системе. Этап с пометкой SYSTEM подразумевает запросы осуществляемые системой к платежному модулю с учетом настроек, заданных при регистрации.
Если при API-запросе к платежному модулю возникла ошибка, необходимо вернуть ответ в формате:
{
"success": false,
"errorMsg": "Текст ошибки"
}Текст, переданный в errorMsg будет показан пользователю. Если при API-запросе к платежному модулю будет возвращен невалидный ответ, информация об этом запишется в Журнал действий с типом записи "Интеграционные платежи".
Регистрация и конфигурация платежного модуля
Для регистрации и конфигурации платежного модуля необходимо использовать метод POST /api/v5/integration-modules/{code}/edit. Если модуль с кодом code уже существует, метод меняет его настройки, в противном случае создается новый интеграционный модуль. Текущие параметры модуля можно получить используя метод GET /api/v5/integration-modules/{code}.
Параметры:
apiKey- API-ключ системыintegrationModule- json, содержащий описание интеграционного модуляintegrationModule[integrations][payment]- настройки конфигурации интеграции с платежной системой
В поле integrationModule[integrations][payment][actions] необходимо указать пути до конкретных callback-методов платежного модуля, к которым будет обращаться CRM система при выполнении действий с интеграционными оплатами. Список методов:
create- создание оплаты (обязательный)approve- подтверждение оплатыcancel- отмена оплатыrefund- возврат
В поле integrationModule[integrations][payment][currencies] необходимо передать список кодов поддерживаемых валют в соответствии со стандартом ISO 4217.
В поле integrationModule[integrations][payment][invoiceTypes] необходимо передать список поддерживаемых типов инвойсов в виде массива. Доступные типы инвойсов:
link- при создании инвойса данного типа должна быть создана ссылка, по которой клиент сможет выполнить платеж.
В поле integrationModule[integrations][payment][shops] необходимо передать список магазинов клиента в платежной системе. Каждый магазин должен содержать наименование name, уникальный код code и статус активности active. В интерфейсе CRM системы будет возможность привязать интеграционный тип оплаты к конкретному магазину платежной системы. Для каждого нового переданного магазина будет автоматически создан новый тип оплаты в системе. Если магазин не активный система предупредит пользователя при добавлении способа оплаты к заказу. Если при обновлении интеграционного модуля какой-либо магазин не будет передан в данном списке, он будет удален из CRM системы, что сделает невозможной дальнейшую работу с оплатами и типами оплат, привязанными к данному магазину.
Пример запроса:
{
"code": "awesome-payment-module",
"clientId": "ea5d01ee-440b-4dbc-ba85-96307e96bdbf",
"baseUrl": "https://payment-module.com",
"accountUrl": "https://payment-module.com/profile/12",
"active": true,
"name": "Awesome Payment Module",
"actions": {
"activity": "activity"
},
"integrations": {
"payment": {
"actions": {
"create": "payment/create",
"approve": "payment/approve",
"cancel": "payment/cancel",
"refund": "payment/refund"
},
"currencies": ["RUB", "EUR"],
"invoiceTypes": ["link"],
"shops": [
{"code": "shop-1","name": "Shop one","active": true},
{"code": "shop-2","name": "Shop two","active": false}
]
}
}
}Статусы инвойсов
В CRM определен набор статусов инвойсов, которые влияют на работу с платежами. От данных статусов зависит логика работы и интерфейс CRM:
pending- статус ожидания оплаты пользователем. Начальный статус, в который переходит инвойс после создания.
При установке данного статуса в интерфейсе CRM будет возможность отменить инвойс, а также отправить письмо со ссылкой на оплату.
waitingForCapture- статус ожидания подтверждения платежа.
Данный статус должен быть установлен, когда деньги заморожены, но еще не списаны. (при холдировании). При установке данного статуса в CRM будет возможность подтвердить, либо отменить списание средств
succeeded- статус успешного платежа. Данный статус должен быть установлен при успешном списании средств со счета клиента.
При установке данного статуса в CRM будет возможность выполнить возврат
canceled- статус отмененной оплаты. Должен быть установлен, если оплата была отмененаrefundSucceeded- статус успешного возврата. Должен быть установлен после успешного осуществления возврата средств клиенту
При изменении статуса инвойса, если для нового статуса настроен маппинг в настройках системы, статус оплаты также будет изменен на соответствующий.
Типовые схемы работы с платежными системами
1. Схема работы с холдированием и автоматическим подтверждением платежа
Платежная система холдирует средства клиента, после чего направляет платежному модулю уведомление. Модуль выполняет проверку данных инвойса, после чего выполняет списание средств, либо отмену платежа. После завершения оплаты модуль обновляет данные инвойса в CRM-системе.
Система Модуль Платежная система Клиент
-------------------------------------------------------------------------------
| | | |
| | | |
Создание ----------------->|--------------------->Создание |
инвойса <------------------|<--инф. об оплате-----оплаты |
| | | |
Отправка ссылки-------------------------------------------------------------->|
на оплату | | |
| | |<----------------Ввод данных
| | | для оплаты
| | | |
| | Холдирование средств |
| | на счете клиента |
| | | |
| | | |
| | Уведомление модуля |
| |<---------------- о холдировании |
| | | |
| | | |
|<------------------Проверка | |
|------------------>инвойса | |
| | | |
| Подтверждение --------------->| |
| списания | |
| | Списание средств |
| | | |
| | | |
| succeeded Обновление | |
|<--------------- статуса <---------------Уведомление о |
| инвойса совершении оплаты |
| | | |
| | | |2. Схема работы с холдированием и ручным подтверждением платежа
Платежная система холдирует средства клиента, после чего направляет уведомление платежному модулю. Модуль выполняет проверку данных инвойса, после чего, в зависимости от результата, отменяет платеж, либо обновляет статус инвойса на waitingForCapture. После принятия / отклонения платежа менеджером, CRM-система уведомляет об этом модуль через соответствующий callback, а модуль в свою очередь должен отменить платеж, либо списать средства. После завершения платежа модуль обновляет данные инвойса в CRM-системе.
Система Модуль Платежная система Клиент
-------------------------------------------------------------------------------
| | | |
| | | |
Создание ----------------->|--------------------->Создание |
инвойса <------------------|<---инф. об оплате----оплаты |
| | | |
Отправка ссылки-------------------------------------------------------------->|
на оплату | | |
| | |<----------------Ввод данных
| | | для оплаты
| | | |
| | Холдирование средств |
| | на счете клиента |
| | | |
| | | |
| | Уведомление модуля |
| |<-----------------о холдировании |
| | | |
|<-------------------Проверка | |
|------OK----------->инвойса | |
| | | |
| waitingForCapture Обновление | |
|<-------------------статуса | |
| инвойса | |
| | | |
Подтверждение-------------->|------------------------>| |
списания | | |
| | Списание средств |
| | | |
| | | |
| succeeded Обновление | |
|<-------------------статуса <-------------Уведомление о |
| инвойса совершении оплаты |
| | | |
| | | |3. Схема работы без холдирования
Подходит для платежных систем, поддерживающих подтверждение готовности принять оплату перед списанием средств. Платежная система запрашивает подтверждение у модуля о готовности принять оплату, модуль проверяет данные инвойса и возвращает результат в платежную систему. Платежная система списывает средства и уведомляет об этом модуль, а модуль обновляет данные инвойса в CRM-системе.
Система Модуль Платежная система Клиент
-------------------------------------------------------------------------------
| | | |
| | | |
Создание ----------------->--------------------> Создание |
инвойса <-----------------|<--инф. об оплате--- оплаты |
| | | |
| | | |
Отправка ссылки-------------------------------------------------------------->|
на оплату | | |
| | | Ввод данных
| | |<----------------для оплаты
| | | |
| | Проверка |
|<------------------Проверка <------------- готовности |
|-----------------> инвойса ------OK------> принять оплату |
| | | |
| | | |
| | Списание средств |
| | | |
| | | |
| succeeded Обновление Уведомление о |
| <----------------статуса <--------------совершении оплаты |
| инвойса | |
| | | |
| | | |Создание оплаты
При выставлении счета в интеграционной оплате система инициирует POST вызов метода указанного в integrationModule[integrations][payment][actions]["create"] конфигурации. Платежный модуль должен создать инвойс в соответствии с переданными параметрами и вернуть ссылку на оплату.
Подтверждение оплаты
При подтверждении оплаты, система инициирует POST вызов метода указанного в integrationModule[integrations][payment][actions]["approve"] конфигурации. Подтверждение оплаты выполняется при нажатии менеджером системы кнопки "Подтвердить" в списке инвойсов. Данное действие доступно только для инвойсов, находящихся в статусе waitingForCapture. При выполнении данного действия платежный модуль должен списать замороженные средства со счета клиента, после чего перевести инвойс в статус succeeded.
Отмена оплаты
При отмене инвойса система инициирует POST вызов метода указанного в integrationModule[integrations][payment][actions]["cancel"] конфигурации. Отмена инвойса выполняется при нажатии менеджером кнопки "Отменить" в списке инвойсов. Отменить можно только инвойсы находящиеся в статусах pending, waitingForCapture. Если инвойс находился в статусе pending, то платежи по данному инвойсу более не должны приниматься платежным модулем. Если инвойс находился в статусе waitingForCapture, то замороженные средства должны быть возвращены на счет клиента. После выполнения отмены инвойс должен быть переведен в статус canceled.
Возврат
При возврате средств клиенту, система инициирует POST вызов метода указанного в integrationModule[integrations][payment][actions]["refund"] конфигурации. Выполнение возврата осуществляется путем нажатия менеджером соответствующей кнопки в списке инвойсов. Возврат доступен только для инвойсов, находящихся в статусе succeeded. После выполнения возврата инвойс должен быть переведен в статус refundSucceeded.
Обновление данных инвойса
При изменении параметров оплаты платежный модуль должен уведомить CRM систему через вызов метода API POST /api/v5/payment/update-invoice. При выполнении данного вызова инвойс на стороне CRM будет обновлен в соответствии с переданными данными. Если изменился статус инвойса, статус оплаты также будет изменен в соответствии с маппингом, настроенным на этапе конфигурации платежного модуля.
Проверка данных инвойса
С момента выставления счета может измениться состав заказа, его стоимость, после чего выставленный счет станет не актуальным. Перед списанием средств платежный модуль должен выполнить проверку. Для этого необходимо выполнить POST вызов метода API POST /api/v5/payment/check, передав необходимые параметры оплаты. Система проверит существование заказа, оплаты, соответствие переданных параметров оплаты параметрам инвойса и вернет результат проверки в ответе.