Интеграция биллинга провайдера по схеме "48 часов" с платежами через кредитные карты

Owned by Denis Kuzmichev
Last updated: Oct 18, 2022 by Nikolay Krasovskiy
4 min read

В дополнение ко всем методам в схеме "48 часов" необходимо реализовать:

  1. В случае нехватки денежных средств, запрос PACKET всегда должен возвращать status = -1
  2. Дополнительные методы от Платформы24: BALANCE и PACKETS
  3. Реализовать метод возвращающий URL к платежной форме в платежной системе (форма должна быть адаптирована для ТВ устройств).

Описание изменений и новых запросов от Платформы24:

В случае нехватки денежных средств, запрос PACKET всегда должен возвращать status = -1

Запрос PACKETS при включении сразу нескольких подписок (при быстрых покупках через ТВ приложение) 

При получении этого запроса в биллинге провайдера необходимо проверить баланс абонента, в случае, если денежных средств хватает, списать их, через API Платформа24 подключить пакеты и вернуть положительный ответ

Запрос: http://<Интергационный урл>/packets?user_id=<Provider_uid>&trf_ids=<ID пакета>,<ID пакета>,...,<ID пакета>

В теле запроса будет json такого типа:

{
    "user": {
        "id": <ID пользователя в платформе 24часаТВ>,
        "phone": "<Номер телефона пользователя>",
        "email": "<email пользователя>",
        "provider_uid": "<Provider_uid – id из биллинговой системы провайдера>",
        "last_name": "<Фамилия пользователя>",
        "username": "<UserName пользователя>",
        "timezone": "Часовой пояс пользователя, например: Indian/Mauritius",
        "first_name": "<Имя пользователя>"
    },
    "type": "packets",
    "packets": [
        {
          "id": <ID желаемого платного пакета в платформе 24часаТВ>,
          "price": "<Стоимость пакета>",
          "is_base": <Тип пакета: true – Базовый, false – дополнительный пакет>,
          "name": "<Название пакета>"
        },
        {
          "id": <ID желаемого платного пакета в платформе 24часаТВ>,
          "price": "<Стоимость пакета>",
          "is_base": <Тип пакета: true – Базовый, false – дополнительный пакет>,
          "name": "<Название пакета>"
        },
        ....
    ]
}

Можно ориентироваться как на параметры URL, так и на json в теле запроса.

В ответ платформа 24часаТВ ожидает json с параметрами - status = 1 - в случае успеха

или status = -1 и errmsg в случае нехватки денежных средств у абонента на покупку сразу всех пакетов.

или status < -1 и errmsg c описанием ошибки, которое транслируется в тв приложение при других причинах.

Положительный ответ в json формате:

 {"status":1}

 Отрицательный ответ в json формате при нехватки денежных средств:

 {"status":-1,"errmsg":"На вашем балансе не хватает денежных средств"}

При других причинах status должен быть меньше -1

После получения status -1 Платформа24 пришлет запрос на получение актуального баланса абонента.

Запрос BALANCE для получения актуального баланса абонента

Тип запроса: POST

Запрос: http://<Интергационный урл>/balance?user_id=<Provider_uid>

В теле запроса будет json такого типа:

{
    "type": "balance",
    "user": {
        "id": <ID пользователя в платформе 24часаТВ>,
        "phone": "<Номер телефона пользователя>",
        "email": "<email пользователя>",
        "provider_uid": "<Provider_uid – id из биллинговой системы провайдера>",
        "last_name": "<Фамилия пользователя>",
        "username": "<UserName пользователя>",
        "timezone": "Часовой пояс пользователя, например: Indian/Mauritius",
        "first_name": "<Имя пользователя>"
    }
}

В ответ Платформа24 ожидает json:

 {"balance":1234.56}

Баланс должен быть в формате decimal, с разделителем точка, в случае другого ответа Платформа24 воспримет это как ошибку и будет невозможно произвести платеж.

Запрос на получение урла на платежную форму в платежной системе

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

Тип запроса: POST

Запрос на: http://<Урл для получения урла на платежную форму>

Параметры в запросе:

UserID - ID у провайдера (provider_uid)
TransactionID - ID транзакции Платформы24
OrderDescription - Описание платежа
Amount - сумма платежа, в формате decimal, разделитель - точка. Вычисляется Платформой24 и расчета: стоимость пакетов - баланс абонента полученный из биллинга провайдера запросом balance.
Currency = RUB
SecurityKey - вычисляемое поле

SecurityKey вычисляется по формуле SHA1("UserID={UserID}&Amount={Amount}&Currency={Currency}&OrderDescription={OrderDescription}&TransactionID={TransactionID}&PrivateSecurityKey={PrivateSecurityKey}").hexdigest(), все параметры в кодировке UTF-8.

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

Положительный ответ в json формате:

 {"redirect_url":"<урл на платежную форму в платежной системе>"}

Все другие ответы считаются ошибочными и в тв приложение будет выведена ошибка, что невозможно совершить платеж.

Отправка статуса транзакции в Платформу24

Для выполнения запросов списания с карты абонента необходимо получить или передать в Платформу24 приватный секретный ключ (PrivateSecurityKey), для вычисления SecurityKey

После получения callback от платежной системы в биллинг провайдера, необходимо передать эту информацию в Платформу24.

При успешном callback  от платежной системы:

    Запрос на: http://<Урл Платформы24>/billing/paysystem/<Название платежной системы>/confirm

    <Урл Платформы24> и <Название платежной системы> сообщается провайдеру Платформой24 при настройке интеграции.

    Тип запроса: GET или POST

    Параметры в запросе:

TransactionID - ID транзакции Платформы24 переданный при запросе на списание с карты или для запроса урла на платежную форму
Amount - сумма платежа, списанной с карты абонента, в формате decimal, разделитель - точка.
Currency = RUB
ExternalTransactionID - ID списания в биллинге
SecurityKey - вычисляемое поле

   SecurityKey вычисляется по формуле SHA1("TransactionID={TransactionID}&Amount={Amount}&ExternalTransactionID={ExternalTransactionID}&Currency={Currency}&PrivateSecurityKey={PrivateSecurityKey}").hexdigest(), все параметры в кодировке UTF-8.

   В ответ Платформа ответит пустым запросом со статусом 200, транзакция в Платформе24 будет помечена, как успешная.

При не успешном callback от платежной системы:

    Запрос на: http://<Урл Платформы24>/billing/paysystem/<Название платежной системы>/fail

    <Урл Платформы24> и <Название платежной системы> сообщается провайдеру Платформой24 при настройке интеграции.

    Тип запроса: GET или POST

    Параметры в запросе:

TransactionID - ID транзакции Платформы24 переданный при запросе на списание с карты или для запроса урла на платежную форму
Amount - сумма платежа, списанной с карты абонента, в формате decimal, разделитель - точка.
Currency = RUB
ExternalTransactionID - ID списания в биллинге
SecurityKey - вычисляемое поле

   SecurityKey вычисляется по формуле SHA1("TransactionID={TransactionID}&Amount={Amount}&ExternalTransactionID={ExternalTransactionID}&Currency={Currency}&PrivateSecurityKey={PrivateSecurityKey}").hexdigest(), все параметры в кодировке UTF-8.

   В ответ Платформа ответит пустым запросом со статусом 200, транзакция в Платформе24 будет помечена, как ошибочная.