Flutterwave

Обзор

Flutterwave — платёжный метод, который позволяет проводить платежи через интернет-банкинг. Оплаты осуществляются через Payment Page и Gate, выплаты и возвраты — через Gate.

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

Тип платёжного метода платежи через интернет-банкинг
Регионы использования ограничений нет
Валюты платежей GHS, KES, NGN, TZS, UGX, USD, ZAR
Конвертация валют на стороне провайдера
Оплаты +
Выплаты +
Оплаты по сохранённым данным
Полные возвраты +
Частичные возвраты +
Опротестования
Особенности
  • реализация Fast Track
  • для проведения платежей через Gate необходимо наличие сертификата PCI DSS у веб-сервиса мерчанта
Организация и стоимость подключения По согласованию с курирующим менеджером ECommPay

Схема работы

В проведении отдельного платежа с использованием Flutterwave задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа ECommPay, а также технические средства провайдера. Оплаты осуществляются через Payment Page и Gate, выплаты и возвраты — через Gate.

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

Интерфейсы Суммы, NGN (или эквивалент) Время
Payment Page CMS Plug-ins Gate Dashboard (Old Dashboard) минимум максимум базовое предельное
Оплаты + + 1,00 500 000,00 до 10 минут *
Выплаты + 100,00 1 000,00 до 10 минут *
Полные возвраты + до 10 минут *
Частичные возвраты + до 10 минут *
Прим.:

* Подробную информацию уточняйте у вашего курирующего менеджера.

Базовое время — среднее расчётное время проведения платежа от момента его инициализации на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время, определяемое для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа.

Предельное время — максимально допустимое время проведения платежа от момента его инициализации на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус decline. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ECommPay.

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

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

Рис.: Оплата через Payment Page

Рис.: Оплата через Gate

Рис.: Возврат через Gate

Рис.: Выплата через Gate

Поддержка со стороны банков

Проведение платежей с применением метода Flutterwave осуществляется через банки, поддерживающие работу с этим методом. Банкам соответствуют свои идентификаторы, которые используются при инициировании выплат через Gate. Далее в таблице в ознакомительных целях представлена информация об этих банках, которую следует уточнять у курирующего менеджера ECommPay.

Табл. 1. Список банков
Банк ID
ACCESS BANK Ghana 269
ACCESS BANK NIGERIA 193
ACCESS MOBILE 194
AFRIBANK NIGERIA PLC 195
African Banking Corp. Bank Ltd 235
Aso Savings and Loans 196
Barclays Bank of Kenya 257
CAL BANK 265
CAPITAL BANK 274
Central Bank of Kenya 256
CFC Stanbic Bank Kenya Limited 234
Chase Bank Limited 233
Citibank N.A. 229
Commercial Bank of Africa Limited 254
Consolidated Bank of Kenya Limited 231
Co-operative Bank of Kenya Limited 226
Coronation Merchant Bank 222
Development Bank of Kenya Limited 247
DIAMOND BANK PLC 197
Diamond Trust Bank Limited 249
ECOBANK Ghana 264
ECO Bank Limited Kenya 239
Ecobank Mobile Nigeria 198
ECOBANK NIGERIA LIMITED 199
ENERGY BANK 270
ENTERPRISE BANK LIMITED 200
Equatorial Commercial Bank Limited 240
Equity Bank Limited 251
Family Bank Ltd 243
FBN MOBILE 201
Fidelity Bank Ghana 275
FIDELITY BANK PLC Nigeria 202
FIRST ALLIED SAVINGS AND LOANS 273
FIRST BANK PLC 203
FIRST CITY MONUMENT BANK PLC 204
FIRST NATIONAL BANK 272
GCB BANK LTD 259
Giro Commercial Bank Limited 238
GTBank Mobile Money 205
GTBANK PLC 206
GUARANTY TRUST BANK 267
Guardian Bank Limited 245
Habib Bank Limited 255
HERITAGE BANK 207
HFC BANK 262
Housing Finance Bank 248
Imperial Bank Limited 236
Investments n Mortgages Bank Limited 246
Jamii Bora Bank 242
Kenya Commercial Bank Limited 253
KEYSTONE BANK PLC 208
K-Rep Bank Limited 250
Middle East Bank Kenya Limited 230
National Bank of Kenya Limited 227
NATIONAL INVESTMENT BANK 260
NIC Bank Limited 237
Oriental Commercial Bank Limited 228
Paramount Universal Bank Limited 241
Parkway 209
PARRALEX BANK 224
PAYCOM 210
Prime Bank Limited 225
Providus Bank 223
ROYAL BANK 271
SKYE BANK PLC 211
STANBIC BANK 266
STANBIC IBTC BANK PLC 212
Stanbic Mobile 213
STANDARD CHARTERED BANK Ghana 258
STANDARD CHARTERED BANK NIGERIA LIMITED 214
STERLING BANK PLC 215
Trans-National Bank Limited 232
UBA Kenya Bank Ltd 252
UNION BANK OF NIGERIA PLC 216
UNITED BANK FOR AFRICA Ghana 268
UNITED BANK FOR AFRICA PLC Nigeria 217
UNITY BANK PLC 218
UNIVERSAL MERCHANT BANK 261
Victoria Commercial Bank Limited 244
WEMA BANK PLC 219
ZENITH BANK Ghana 263
ZENITH BANK PLC Nigeria 220
ZENITH Mobile Nigeria 221

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

Оплаты через Payment Page

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

Оплата через Payment Page с использованием метода Flutterwave со стороны веб-сервиса выполняется стандартным образом: через отправку запроса, содержащего требуемые параметры и подпись, на рабочий URL ECommPay и приём оповещения о результате оплаты. Полная схема проведения оплаты представлена далее.

Рис.: Проведение оплаты через Payment Page

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

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

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

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

  1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
    • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта;
    • payment_currency — валюта платежа в формате ISO-4217 alpha-3;
    • payment_amount — сумма платежа в минорных единицах,
    • customer_id — идентификатор пользователя уникальный в рамках проекта.
  2. Валютой платежа могут быть GHS, KES, NGN, TZS, UGX, USD, ZAR.
  3. Дополнительно должен использоваться параметр payment_description — описание платежа.
  4. Для предварительного выбора метода Flutterwave необходимо указывать код платёжного метода в параметре force_payment_methodflutterwave.
  5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page.
  6. После определения всех параметров необходимо составить подпись. Подробную информацию см. в Работа с подписью к данным.

Таким образом, корректный запрос на открытие платёжной формы с применением метода Flutterwave должен содержать идентификаторы проекта, пользователя и платежа, а также валюту, сумму и описание платежа:

EPayWidget.run(
    { payment_id: 'X03936', 
      payment_amount: 1000, 
      payment_currency: 'NGN', 
      project_id: 102,
      customer_id: 'customer1',
      payment_description: 'test PP sale', 
      signature: "gUi9x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
    }
)

Детальная информация обо всех указанных параметрах приведена в разделе Параметры открытия платежной формы Payment Page.

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

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

Рис.: Пример оповещения о проведенной оплате

 {
        "project_id": 258,
        "payment": {
            "id": "TEST_155",
            "type": "purchase",
            "status": "success",
            "date": "2019-02-14T13:39:53+0000",
            "method": "flutterwave",
            "sum": {
                "amount": 200,
                "currency": "NGN"
            },
            "description": ""
        },
        "account": {
            "number": "521178******9110"
        },
        "customer": {
            "id": "667"
        },
        "operation": {
            "id": 14376000003171,
            "type": "sale",
            "status": "success",
            "date": "2019-02-14T13:39:53+0000",
            "created_date": "2019-02-14T13:35:18+0000",
            "request_id": "e851ad352570d8d42e92e72becf792120bbc7339-37d3aebe73b4d05fd42fbbb0b5e4da0ead53180f",
            "sum_initial": {
                "amount": 200,
                "currency": "NGN"
            },
            "sum_converted": {
                "amount": 200,
                "currency": "NGN"
            },
            "provider": {
                "id": 1149,
                "payment_id": "FLW119179586",
                "date": "2019-02-14T13:39:07+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "aqzhui5DMRWHsD9k7xGSdOZmQwWsILG9VR7JhvXeRGn3s3eqzsNStqR8no8bdeDvpXEQj6ef5XxTX5v3bQuR2w=="
    }

В данном примере оповещение свидетельствует о том, что в рамках проекта 258 пользователь с идентификатором 667 успешно совершил оплату на сумму 2,00 NGN.

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

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

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

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

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

  1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay.
  2. Осуществить перенаправление пользователя к сервису Flutterwave для совершения оплаты.
  3. Принять оповещение о результате оплаты.

Рис.: Проведение оплаты через Gate

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

Информация о формате запросов и параметрах инициализации оплат методом ECommPay через Gate, а также о формате оповещений о результатах оплат приведена далее; общая информация о работе с API — в разделе Работа с API.

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

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

  1. Должен использоваться запрос v2/payment/flutterwave/sale, отправляемый методом POST.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения о запросе:
      • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным);
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в минорных единицах,
      • currency — валюта платежа в формате ISO-4217 alpha-3.
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор, уникальный в рамках проекта,
      • ip_address — IP-адрес;
  3. Валютой платежа могут быть GHS, KES, NGN, TZS, UGX, USD, ZAR.
  4. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату с применением метода Flutterwave должен содержать идентификаторы проекта и платежа, а также валюту и сумму платежа:

Рис.: Пример запроса на оплату

{
  "general": {
    "project_id": 258,
    "payment_id": "TEST_155",
    "signature": "i97Z0qDJGmCr0YzucLO2q+KgQtWxG8bBQcAzr74S2VJLrThxL4fwOUcZhdOULQWfwa7kf/yaaxH7V46k/Ho5Ag=="
  },
  "customer": {
    "id": "667",
    "ip_address": "87.245.207.226",
    "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36",
    "device_type": "Desktop",
    "screen_res": "1920x1080",
    "session_id": "bsht6c8pd94v9r8gr41b31vhu7"
  },
  "payment": {
    "amount": 200,
    "currency": "NGN"
  }
}

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

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

Рис.: Пример оповещения о проведенной оплате

 {
        "project_id": 258,
        "payment": {
            "id": "TEST_155",
            "type": "purchase",
            "status": "success",
            "date": "2019-02-14T13:39:53+0000",
            "method": "flutterwave",
            "sum": {
                "amount": 200,
                "currency": "NGN"
            },
            "description": ""
        },
        "account": {
            "number": "521178******9110"
        },
        "customer": {
            "id": "667"
        },
        "operation": {
            "id": 14376000003171,
            "type": "sale",
            "status": "success",
            "date": "2019-02-14T13:39:53+0000",
            "created_date": "2019-02-14T13:35:18+0000",
            "request_id": "e851ad352570d8d42e92e72becf792120bbc7339-37d3aebe73b4d05fd42fbbb0b5e4da0ead53180f",
            "sum_initial": {
                "amount": 200,
                "currency": "NGN"
            },
            "sum_converted": {
                "amount": 200,
                "currency": "NGN"
            },
            "provider": {
                "id": 1149,
                "payment_id": "FLW119179586",
                "date": "2019-02-14T13:39:07+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "aqzhui5DMRWHsD9k7xGSdOZmQwWsILG9VR7JhvXeRGn3s3eqzsNStqR8no8bdeDvpXEQj6ef5XxTX5v3bQuR2w=="
    }

В данном примере оповещение свидетельствует о том, что в рамках проекта 258 пользователь с идентификатором 667 успешно совершил оплату на сумму 2,00 NGN.

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

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

Возвраты через Gate

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

Flutterwave поддерживает проведение полных и частичных возвратов. Проведение возврата с использованием метода Flutterwave выполняется стандартным для Gate способом: с отправкой запроса, содержащего требуемые параметры и подпись, на рабочий URL ECommPay и с последующей обработкой этого запроса платёжной платформой. Полная схема проведения возврата представлена далее.

Рис.: Проведение возврата через Gate

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

Информация о формате запросов и параметрах инициализации возвратов методом Flutterwave через Gate, а также о формате оповещений о результатах возвратов приведена далее, общая информация о работе с API — Работа с API.

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

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

  1. Должен использоваться запрос v2/payment/flutterwave/refund, отправляемый методом POST.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения о запросе:
      • project_id — идентификатор проекта;
      • payment_id — идентификатор платежа;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
    • payment — объект, содержащий сведения о возврате :
      • description — комментарий или описание возврата,
      • amount — сумма возврата в минорных единицах валюты (обязательный при частичном возврате),
      • currency — валюта возврата в формате ISO-4217 alpha-3 (обязательный при частичном возврате).
  3. Валютой платежа могут быть GHS, KES, NGN, TZS, UGX, USD, ZAR.
  4. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на возврат с применением метода Flutterwave должен содержать идентификаторы проекта и платежа:

Рис.: Пример запроса на возврат

{
  "general": {
    "project_id": 257,
    "payment_id": "TEST_155",
    "signature": "EVUbhYJ7CjhJlawmfCaNXSPsPPU2XvVMOnDjEyfEdeeVt6u...==",
  },
  "payment": {
    "amount": 50000,
    "currency": "NGN",
    "description": "TEST_155"
  }
}

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

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

Рис.: Пример оповещения о проведенном возврате

 {
        "project_id": 257,
        "payment": {
            "id": "TEST_155",
            "type": "purchase",
            "status": "partially refunded",
            "date": "2019-02-18T06:18:01+0000",
            "method": "flutterwave",
            "sum": {
                "amount": 40000,
                "currency": "NGN"
            },
            "description": "TEST_155"
        },
        "operation": {
            "id": 258000003219,
            "type": "refund",
            "status": "success",
            "date": "2019-02-18T06:18:01+0000",
            "created_date": "2019-02-18T06:17:52+0000",
            "request_id": "dda6eb029059832eb1",
            "sum_initial": {
                "amount": 10000,
                "currency": "NGN"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "NGN"
            },
            "provider": {
                "id": 1149,
                "payment_id": "25960166",
                "date": "2019-02-18T06:18:00+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "L3DDG4SK3dukjBjT8ZZfOL4X/jE1/BgKp5LI2+putJA/U4DxogWEKCqbOWewI6dt4C7EX1BEkKL4QGH1nNNWRw=="
    }

В данном случае оповещение свидетельствует о том, что в рамках проекта 257 был успешно проведён частичный возврат в размере 100,00 NGN.

Рис.: Пример оповещения об отказе в проведении возврата

 {
        "project_id": 257,
        "payment": {
            "id": "TEST_155",
            "type": "purchase",
            "status": "success",
            "date": "2019-02-13T12:35:49+0000",
            "method": "flutterwave",
            "sum": {
                "amount": 50000,
                "currency": "NGN"
            },
            "description": "TEST_155"
        },
        "operation": {
            "id": 258000003164,
            "type": "refund",
            "status": "decline",
            "date": "2019-02-15T13:36:28+0000",
            "created_date": "2019-02-15T13:36:27+0000",
            "request_id": "354c11cdc403a2",
            "sum_initial": {
                "amount": 10000,
                "currency": "NGN"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "NGN"
            },
            "provider": {
                "id": 1149,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "3283",
            "message": "Refund amount more than init amount"
        },
        "signature": "1aw64dc0nH3bKt4XJr8F6UXhC352gaSGEvSrHz8zsg4mOR3kcHGRYAxYPI9sqQ57/2KWDwhjfNf2XY2ZuDMovg=="
    }

В этом примере возврат был отклонён по причине того, что значение суммы в запросе на возврат больше суммы в инитной оплате.

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

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

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

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

Проведение выплаты с использованием метода Flutterwave выполняется стандартным для Gate способом: с отправкой запроса, содержащего требуемые параметры и подпись, на рабочий URL ECommPay и с последующей обработкой этого запроса платёжной платформой. Полная схема проведения выплаты представлена далее.

Рис.: Проведение выплаты через Gate

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

Информация о формате запросов и параметрах инициализации выплат методом Flutterwave через Gate, а также о формате оповещений о результатах выплат приведена далее, общая информация о работе с API — Работа с API.

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

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

  1. Должен использоваться запрос v2/payment/flutterwave/payout, отправляемый методом POST.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения о запросе:
      • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор,
      • ip_address — IP-адрес;
    • account — объект, содержащий сведения о банковском счёте пользователя:
      • number — номер счёта,
      • bank_id — идентификатор банка;
    • payment — сведения о платеже:
      • amount — сумма платежа в минорных единицах,
      • currency — валюта платежа в формате ISO-4217 alpha-3.
  3. Валютой платежа могут быть GHS, KES, NGN, TZS, UGX, USD, ZAR.
  4. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на выплату с применением метода Flutterwave должен общие данные о запросе, данные о пользователе, счёте и платеже:

Рис.: Пример запроса на выплату

{
  "general": {
    "project_id": 258,
    "payment_id": "flutterwave-payout-00118",
    "signature": "H6Q9ZfsreIyrOva9CuxO/34IignE3ZZEQepbpNmZM/V5jdk...=="
  },
  "account": {
    "number": "0017704603", 
    "bank_id": "308"
  },
  "customer": {
    "id": "cust000001",
    "ip_address": "127.0.0.1"
  },
  "payment": {
    "amount": 1000,
    "currency": "NGN",
    "description": "payout"
  }
}

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

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

Рис.: Пример оповещения о проведенной выплате

{
        "project_id": 258,
        "payment": {
            "id": "flutter-wave-payout-00118",
            "type": "payout",
            "status": "success",
            "date": "2019-02-15T06:52:42+0000",
            "method": "flutterwave",
            "sum": {
                "amount": 1000,
                "currency": "NGN"
            },
            "description": "payout"
        },
        "account": {
            "number": "0017704603"
        },
        "customer": {
            "id": "cust000001"
        },
        "operation": {
            "id": 3950000003217,
            "type": "payout",
            "status": "success",
            "date": "2019-02-15T06:52:42+0000",
            "created_date": "2019-02-15T06:48:39+0000",
            "request_id": "b8dcdecbdd842017c91efd752a71a2afa790884b-70151ed2a85d685602a73045c2e07fdbf027182a",
            "sum_initial": {
                "amount": 1000,
                "currency": "NGN"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "NGN"
            },
            "provider": {
                "id": 1149,
                "payment_id": "53313",
                "date": "2019-02-15T06:48:40+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "Qg9YTDQhe6VG4O9WtvtW4VqQRfWVb/iDs4z8TKuYGq1DA3sFCtBwKCxWXSjytuX+FpBqAiomhYD1GBGzo3HG1w=="
    }

В данном случае оповещение свидетельствует о том, что в рамках проекта 258 для пользователя cust000001 была успешно проведена выплата в размере 10,00 NGN.

Рис.: Пример оповещения об отказе в проведении выплаты

{
        "project_id": 257,
        "payment": {
            "id": "flutter-wave-payout-0010",
            "type": "payout",
            "status": "decline",
            "date": "2019-02-06T12:34:37+0000",
            "method": "flutterwave",
            "sum": {
                "amount": 900,
                "currency": "NGN"
            },
            "description": "payout"
        },
        "account": {
            "number": "0017704603"
        },
        "customer": {
            "id": "cust000001"
        },
        "errors": [
            {
                "code": "3028",
                "message": "Insufficient funds on merchant balance",
                "description": "public: BALANCE_INSUFFICIENT_FUNDS"
            }
        ],
        "operation": {
            "id": 2591000003033,
            "type": "payout",
            "status": "decline",
            "date": "2019-02-06T12:34:37+0000",
            "created_date": "2019-02-06T12:34:36+0000",
            "request_id": "07ff210d268901074cbd161e8d75ac28b81b5c41-5b123cb84a1a55362c98b6fd801b682884576779",
            "sum_initial": {
                "amount": 900,
                "currency": "NGN"
            },
            "sum_converted": {
                "amount": 900,
                "currency": "NGN"
            },
            "provider": {
                "id": 1149,
                "payment_id": ""
            },
            "code": "3028",
            "message": "Insufficient funds on merchant balance"
        },
        "signature": "Y7PNifR1g7rBXJPBAGoypaBMg8ixa5LKmsyU3f3ZXjb0TgPD7X2zcgtRLrJmTIvlyqOTwaW1kXkr3VcrM0uz4Q=="
    }

В этом примере выплата была отклонена по причине недостатка средств на счёте.

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

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

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

Как и при работе с другими платёжными методами, которые предоставляет ECommPay, при использовании метода Flutterwave доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.

Всю необходимую информацию можно получать и анализировать средствами Dashboard (Old Dashboard), в том числе с помощью аналитических панелей на вкладке Analytics.

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

  • Dashboard (Old Dashboard) позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
  • Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.

С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ECommPay.