Hizli QR

Обзор

Hizli QR — платёжный метод, который поддерживает проведение оплат с помощью интернет–банкинга турецких банков. Для работы с этим методом доступно проведение оплат через Payment Page и Gate.

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

Тип платёжного метода Интернет–банкинг
Регионы использования Турция
Валюты платежей TRY
Конвертация валют
Оплаты +
Выплаты
Оплаты по сохранённым данным
Полные возвраты
Частичные возвраты
Опротестования
Особенности
  • Сумма оплаты должна быть кратна 10,00 TRY
  • Платежи обрабатываются с учетом рабочего времени сервиса с 08:00:00 до 04:00:00 (GMT+3)
Организация и стоимость подключения По согласованию с курирующим менеджером ECommPay

Схема работы

В проведении отдельного платежа с использованием Hizli QR задействуются веб–сервис мерчанта, один из интерфейсов и платёжная платформа ECommPay, а также технические средства сервиса Hizli QR.



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

Интерфейсы Суммы, TRY Время**
Payment Page CMS Plug–ins Gate Dashboard (Old Dashboard) Минимум Максимум Базовое Предельное
Оплаты + + 100,00 до 4 000,00 * 5 минут 1 час

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

** Базовое и предельное время определяются следующим образом:

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

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

Проведение оплат с использованием метода Hizli QR выполняется с перенаправлением пользователей к сервисам Hizli QR.

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



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



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

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

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

Для оплаты через Payment Page с использованием метода Hizli QR со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ECommPay и принять оповещение о результате оплаты. При этом метод Hizli QR можно делать предварительно выбранным (подробнее — в разделе Предварительный выбор платежного метода). Полная схема проведения оплаты представлена далее.



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

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

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

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

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

  1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
    • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
    • payment_id — идентификатор платежа уникальный в рамках проекта;
    • payment_amount — сумма платежа в минорных единицах валюты;
    • payment_currency — валюта платежа в формате ISO-4217 alpha-3;
    • customer_id — идентификатор пользователя уникальный в рамках проекта.
  2. Валютой платежа может быть только TRY.
  3. Обязательным параметром также является customer_id — идентификатор пользователя в проекте.
  4. Дополнительно должны передаваться следующие параметры с данными о пользователе:
    • email — адрес электронной почты,
    • first_name — имя,
    • last_name — фамилия,
    • day_of_birth — дата рождения,
    • billing.address — улица, дом/квартира платежного адреса,
    • billing.city — город платежного адреса,
    • billing.country — страна платежного адреса,
    • billing.postal — почтовый индекс платежного адреса;
    В случае если данные параметры не переданы в запросе на оплату, они будут запрошены у пользователя на Payment Page.
  5. Страной пользователя может быть только Турция: customer_billing_country: "TR".
  6. Для предварительного выбора метода Hizli QR необходимо указывать в параметре force_payment_method код платёжного метода — hizliqr.
  7. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page.
  8. После указания целевых параметров необходимо составлять подпись (подробнее — в разделе Работа с подписью к данным).

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

EPayWidget.run(
    { payment_id: 'TEST_154', 
      payment_amount: 10000, 
      payment_currency: 'TRY, 
      project_id: 818,
      customer_id: 'customer1',
      signature: "xq9k0XaXE0Ig0s%2B4%2BM2gtmkytwe3%2BP1pzXNsug19oD1upt%2F%2BABrIsG37IPKbfw%3D%3D"
    }
)

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

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

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

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

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

 {
        "project_id": 818,
        "payment": {
            "id": "ORDER_ID_gev",
            "type": "purchase",
            "status": "success",
            "date": "2019-05-30T07:48:26+0000",
            "method": "hizli",
            "sum": {
                "amount": 10000,
                "currency": "TRY"
            },
            "description": "u0443"
        },
        "customer": {
            "id": "Tyrkman"
        },
        "operation": {
            "id": 1246,
            "type": "sale",
            "status": "success",
            "date": "2019-05-30T07:48:27+0000",
            "created_date": "2019-05-30T07:48:09+0000",
            "request_id": "6cb000fda4402a4c7f9f301eec3d8d52",
            "sum_initial": {
                "amount": 10000,
                "currency": "TRY"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "TRY"
            },
            "provider": {
                "id": 1404,
                "payment_id": "19gla-39nzp7uhwc-5aYk",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "H9j5S+t+jKeVs717ET765vHJKIISkNb4YdkIeJCFhJxiKNLstiVoAUrWbDAHSQ=="
    }

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

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

 {
        "project_id": 818,
        "payment": {
            "id": "ORDER_ID_gev",
            "type": "purchase",
            "status": "decline",
            "date": "2019-05-30T07:49:33+0000",
            "method": "hizli",
            "sum": {
                "amount": 101000,
                "currency": "TRY"
            },
            "description": "u043d"
        },
        "customer": {
            "id": "Tyrkman"
        },
        "operation": {
            "id": 2000001261,
            "type": "sale",
            "status": "decline",
            "date": "2019-03-27T10:58:26+0000",
            "created_date": "2019-03-27T10:58:23+0000",
            "request_id": "65a09bb143bc051a9fa326155ac509768",
            "sum_initial": {
                "amount": 101000,
                "currency": "TRY"
            },
            "sum_converted": {
                "amount": 101000,
                "currency": "TRY"
            },
            "provider": {
                "id": 1404,
                "payment_id": "19gla-39nzp7uhwc",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "Hn53oZbiN1/yTQXuMuLih+ojsDgarVO2K8h7uqYpyKJDayaAjnFGm1PFkqCA+E/nVQ1Hcg=="
    }

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

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

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

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

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

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


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

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

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

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

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

  1. Должен использоваться запрос v2/payment/turkey-qr/hizli/sale, отправляемый методом POST. Этот запрос относится к группе запросов для проведения платежей /v2/payment/turkey-qr/{payment_method}/sale.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор,
      • ip_address — IP-адрес,
      • email — адрес электронной почты,
      • first_name — имя,
      • last_name — фамилия,
      • day_of_birth — дата рождения,
      • billing.address — улица, дом/квартира платежного адреса,
      • billing.city — город платежного адреса,
      • billing.country — страна платежного адреса,
      • billing.postal — почтовый индекс платежного адреса;
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в минорных единицах валюты,
      • currency — валюта платежа в формате ISO-4217 alpha-3;
    • return_url — URL для перенаправления пользователя с сайта банка:
      • success — URL для перенаправления пользователя при проведенной оплате.
  3. Валютой платежа может быть только TRY.
  4. Страной пользователя может быть только Турция: customer.billing_country: "TR".
  5. Дополнительно могут использоваться все параметры, указанные в спецификации.

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

{
  "general": {
    "project_id": 818,
    "payment_id": "ORDER_ID_gev",
    "signature": "+K6jllym+PtObocZ1ySEmETmkJdsfgaGp+3bWA4NcWxfWJTXdESkijfsBeR6bKROUsslA=="
  },
  "customer": {
    "id": "theBestCustomer",
    "email": "turkeyqr@trpay.tr",
    "first_name": "Itan",
    "last_name": "Tyrkman",
    "billing": {
      "country": "TR",
      "city": "Antalia",
      "address": "Street 10, 22",
      "postal": "1545645"
    },
    "day_of_birth": "03-11-2002",
    "ip_address": "1.2.3.4"
  },
  "payment": {
    "amount": 51000,
    "currency": "TRY"
  },
  "return_url": {
    "success": "https://yandex.ru"
  }
}

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

Для перенаправления пользователя от веб-сервиса на сайт сервиса Hizli QR необходимо принять оповещение от платёжной платформы, содержащее ссылку для перенаправления в параметре redirect_data.url и данные для отправки в теле запроса redirect_data.body, и использовать эти параметры при открытии HTML-страницы сайта методом, указанным в redirect_data.method.

Далее приведён фрагмент оповещения, содержащего токен на оплату.

"redirect_data": {
    "method": "GET",
    "body": {
      "status": "PENDING",
      "amount": "10000",
      "currency": "TRY",
      "type": "DEPOSIT",
      "referenceNo": "100000",
      "operation": "DIRECT",
      "returnUrl": "https://test.tr",
      "paymentMethod": "QRCODE",
      "transactionId": "7rwvs-vd9z3b4gnu-rb",
      "message": "Waiting",
      "code": "283",
      "language": "en",
      "purchaseUrl": "http://hizli/a/redirect?referenceNo=100000&returnUrl=https://test.tr"
    },
    "encrypted": [],
    "url": "http://hizli/a/redirect?referenceNo=100000&returnUrl=https://test.tr"
  },

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

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

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

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

 {
        "project_id": 818,
        "payment": {
            "id": "ORDER_ID_gev",
            "type": "purchase",
            "status": "success",
            "date": "2019-05-30T07:48:26+0000",
            "method": "hizli",
            "sum": {
                "amount": 10000,
                "currency": "TRY"
            },
            "description": "u0443"
        },
        "customer": {
            "id": "Tyrkman"
        },
        "operation": {
            "id": 1246,
            "type": "sale",
            "status": "success",
            "date": "2019-05-30T07:48:27+0000",
            "created_date": "2019-05-30T07:48:09+0000",
            "request_id": "6cb000fda4402a4c7f9f301eec3d8d52",
            "sum_initial": {
                "amount": 10000,
                "currency": "TRY"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "TRY"
            },
            "provider": {
                "id": 1404,
                "payment_id": "19gla-39nzp7uhwc-5aYk",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "H9j5S+t+jKeVs717ET765vHJKIISkNb4YdkIeJCFhJxiKNLstiVoAUrWbDAHSQ=="
    }

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

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

 {
        "project_id": 818,
        "payment": {
            "id": "ORDER_ID_gev",
            "type": "purchase",
            "status": "decline",
            "date": "2019-05-30T07:49:33+0000",
            "method": "hizli",
            "sum": {
                "amount": 101000,
                "currency": "TRY"
            },
            "description": "u043d"
        },
        "customer": {
            "id": "Tyrkman"
        },
        "operation": {
            "id": 2000001261,
            "type": "sale",
            "status": "decline",
            "date": "2019-03-27T10:58:26+0000",
            "created_date": "2019-03-27T10:58:23+0000",
            "request_id": "65a09bb143bc051a9fa326155ac509768",
            "sum_initial": {
                "amount": 101000,
                "currency": "TRY"
            },
            "sum_converted": {
                "amount": 101000,
                "currency": "TRY"
            },
            "provider": {
                "id": 1404,
                "payment_id": "19gla-39nzp7uhwc",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "Hn53oZbiN1/yTQXuMuLih+ojsDgarVO2K8h7uqYpyKJDayaAjnFGm1PFkqCA+E/nVQ1Hcg=="
    }

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

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

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

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

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

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

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

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