Порядок интеграции платежной системы через API

Работа с API производится в соответствии с правилами работы с API. Для интеграции используются API-методы секции Платежи.

Для интеграции необходимо:

  1. USER Запросить у пользователя API-ключ для доступа к системе
  2. API Зарегистрировать новый интеграционный платежный модуль
  3. USER Произвести необходимые настройки на странице настройки интеграции в платежном модуле
  4. USER Создать типы оплаты, связанные с магазинами созданного платежного модуля
  5. SYSTEM Запросы связанные с оплатами будет инициировать система в процессе работы пользователя
  6. 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}.

Параметры:

В поле integrationModule[integrations][payment][actions] необходимо указать пути до конкретных callback-методов платежного модуля, к которым будет обращаться CRM система при выполнении действий с интеграционными оплатами. Список методов:

В поле integrationModule[integrations][payment][currencies] необходимо передать список кодов поддерживаемых валют в соответствии со стандартом ISO 4217

В поле integrationModule[integrations][payment][invoiceTypes] необходимо передать список поддерживаемых типов инвойсов в виде массива. Доступные типы инвойсов:

В поле 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:

При установке данного статуса в интерфейсе CRM будет возможность отменить инвойс, а также отправить письмо со ссылкой на оплату.

Данный статус должен быть установлен, когда деньги заморожены, но еще не списаны. (при холдировании). При установке данного статуса в CRM будет возможность подтвердить, либо отменить списание средств

При установке данного статуса в CRM будет возможность выполнить возврат

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

Типовые схемы работы с платежными системами

1. Схема работы с холдированием и автоматическим подтверждением платежа

Платежная система холдирует средства клиента, после чего направляет платежному модулю уведомление. Модуль выполняет проверку данных инвойса, после чего выполняет списание средств, либо отмену платежа. После завершения оплаты модуль обновляет данные инвойса в CRM-системе.


     retailCRM                Модуль             Платежная система            Клиент
    -------------------------------------------------------------------------------
       |                      |                         |                      |
       |                      |                         |                      |
   Создание ----------------->|--------------------->Создание                  |
   инвойса <------------------|<--инф. об оплате-----оплаты                    |
       |                      |                         |                      |
 Отправка ссылки-------------------------------------------------------------->|
   на оплату                  |                         |                      |
       |                      |                         |<----------------Ввод данных
       |                      |                         |                 для оплаты
       |                      |                         |                      |
       |                      |                  Холдирование средств          |
       |                      |                  на счете клиента              |
       |                      |                         |                      |
       |                      |                         |                      |
       |                      |                  Уведомление модуля            |
       |                      |<---------------- о холдировании                |
       |                      |                         |                      |
       |                      |                         |                      |
       |<------------------Проверка                     |                      |
       |------------------>инвойса                      |                      |
       |                      |                         |                      |
       |                  Подтверждение --------------->|                      |
       |                  списания                      |                      |
       |                      |                   Списание средств             |
       |                      |                         |                      |
       |                      |                         |                      |
       |   succeeded      Обновление                    |                      |
       |<---------------  статуса <---------------Уведомление о                |
       |                  инвойса                 совершении оплаты            |
       |                      |                         |                      |
       |                      |                         |                      |

2. Схема работы с холдированием и ручным подтверждением платежа

Платежная система холдирует средства клиента, после чего направляет уведомление платежному модулю. Модуль выполняет проверку данных инвойса, после чего, в зависимости от результата, отменяет платеж, либо обновляет статус инвойса на waitingForCapture. После принятия / отклонения платежа менеджером, CRM-система уведомляет об этом модуль через соответствующий callback, а модуль в свою очередь должен отменить платеж, либо списать средства. После завершения платежа модуль обновляет данные инвойса в CRM-системе.


   retailCRM                Модуль             Платежная система            Клиент
   -------------------------------------------------------------------------------
       |                      |                         |                      |
       |                      |                         |                      |
   Создание ----------------->|--------------------->Создание                  |
   инвойса <------------------|<---инф. об оплате----оплаты                    |
       |                      |                         |                      |
 Отправка ссылки-------------------------------------------------------------->|
   на оплату                  |                         |                      |
       |                      |                         |<----------------Ввод данных
       |                      |                         |                 для оплаты
       |                      |                         |                      |
       |                      |                  Холдирование средств          |
       |                      |                  на счете клиента              |
       |                      |                         |                      |
       |                      |                         |                      |
       |                      |                  Уведомление модуля            |
       |                      |<-----------------о холдировании                |
       |                      |                         |                      |
       |<-------------------Проверка                    |                      |
       |------OK----------->инвойса                     |                      |
       |                      |                         |                      |
       | waitingForCapture  Обновление                  |                      |
       |<-------------------статуса                     |                      |
       |                    инвойса                     |                      |
       |                      |                         |                      |
  Подтверждение-------------->|------------------------>|                      |
  списания                    |                         |                      |
       |                      |                   Списание средств             |
       |                      |                         |                      |
       |                      |                         |                      |
       |  succeeded         Обновление                  |                      |
       |<-------------------статуса <-------------Уведомление о                |
       |                    инвойса               совершении оплаты            |
       |                      |                         |                      |
       |                      |                         |                      |

3. Схема работы без холдирования

Подходит для платежных систем, поддерживающих подтверждение готовности принять оплату перед списанием средств. Платежная система запрашивает подтверждение у модуля о готовности принять оплату, модуль проверяет данные инвойса и возвращает результат в платежную систему. Платежная система списывает средства и уведомляет об этом модуль, а модуль обновляет данные инвойса в CRM-системе.


   retailCRM                Модуль             Платежная система            Клиент
   -------------------------------------------------------------------------------
       |                      |                         |                      |
       |                      |                         |                      |
   Создание ----------------->-------------------->  Создание                  |
   инвойса  <-----------------|<--инф. об оплате---  оплаты                    |
       |                      |                         |                      |
       |                      |                         |                      |
 Отправка ссылки-------------------------------------------------------------->|
   на оплату                  |                         |                      |
       |                      |                         |                 Ввод данных
       |                      |                         |<----------------для оплаты
       |                      |                         |                      |
       |                      |                    Проверка                    |
       |<------------------Проверка <------------- готовности                  |
       |-----------------> инвойса ------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/updateInvoice. При выполнении данного вызова инвойс на стороне CRM будет обновлен в соответствии с переданными данными. Если изменился статус инвойса, статус оплаты также будет изменен в соответствии с маппингом, настроенным на этапе конфигурации платежного модуля.

Проверка данных инвойса

С момента выставления счета может измениться состав заказа, его стоимость, после чего выставленный счет станет не актуальным. Перед списанием средств платежный модуль должен выполнить проверку. Для этого необходимо выполнить POST вызов метода API POST /api/v5/payment/check, передав необходимые параметры оплаты. Система проверит существование заказа, оплаты, соответствие переданных параметров оплаты параметрам инвойса и вернет результат проверки в ответе.


Редакция от 23.10.2020 13:03