Kassa24 Terminal BVU

Схема работы

В проведении отдельной оплаты с использованием платежного метода Kassa24 Terminal BVU задействуются веб-сервис мерчанта, один из интерфейсов и платежная платформа JetPay, а также сервис Kassa24 Terminal BVU.

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

	Интерфейсы				Суммы		Время
	Payment Page	CMS Plug-ins	Gate	Dashboard	минимум	максимум	базовое	предельное
Оплата							1 минута	36 суток

Уточнить минимальную и максимальную сумму платежа, доступную в вашем проекте, вы можете в Dashboard. Для этого в Dashboard перейдите в раздел Проекты и выберите вкладку Платежные методы.

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

Проведение оплат с использованием метода Kassa24 Terminal BVU выполняется через виртуальные терминалы Kassa24 BVU.

Рис.: Оплата Kassa24 Terminal BVU

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

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

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

1. Обработать запрос на проверку существования лицевого счета пользователя.
2. Отправить ответ с информацией о существовании лицевого счета пользователя.
3. Обработать запрос на получение идентификатора платежа на стороне веб-сервиса.
4. Отправить ответ с идентификатором платежа.
5. Принять оповещение о результате оплаты.

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

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

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

1. Запрос verify для проверки существования лицевого счета пользователя отправляется платежной платформой на URL-адрес веб-сервиса методом POST.
2. Запрос содержит следующие обязательные параметры:
   • type — тип операции на стороне веб-сервиса, значение параметра всегда verify;
   • customer_id — имя учетной записи пользователя в сервисе мерчанта, которое пользователь вводит в виртуальном терминале;
   • project_id — идентификатор проекта, полученный от JetPay при интеграции;
   • signature — подпись запроса (подробнее — в разделе Использование подписи к данным).

   Рис.: Пример данных из запроса на проверку существования лицевого счета пользователя

   {
       "type": "verify",   
       "customer_id": "7123456789",
       "project_id": 1234,
       "signature": "e19695449545fac562843ca06e7e0f3e51281ad6"
   }

3. Ответ на запрос verify должен быть отправлен синхронно и содержать следующие обязательные параметры:
   • code — код ответа на запрос;
   • currency — код валюты платежа в формате ISO-4217 alpha-3.

   Табл. 1. Допустимые коды ответов

   Код	Описание
   0	Операция успешна
   400	Ошибка подписи
   404	Лицевой счет пользователя не существует
   500	Общая ошибка, причина должна быть описана в необязательном параметре error_description

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

   • additional_customer_id — идентификатор пользователя, уникальный в рамках проекта, который используется для идентификации пользователя в платежной платформе JetPay;
   • error_description — описание ошибки от мерчанта.

   В случае успеха проверки наличия лицевого счета ответ должен содержать код ответа на запрос и валюту платежа.

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

   {
      "code": 0,
      "currency": "KZT",
      "additional_customer_id": "HFVDW42345"
   }

   Если обнаружить запрошенный лицевой счет не удалось, ответ на запрос должен содержать код ответа на запрос и сообщение об ошибке.

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

   { 
      "code": 404,
      "error_description": "Account does not exist"
   }

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

1. Запрос check_deposit для получения идентификатора платежа на стороне веб-сервиса отправляется методом POST на заданный URL веб-сервиса.
2. Запрос содержит следующие обязательные параметры:
   • type — тип операции на стороне веб-сервиса, значение параметра всегда check_deposit;
   • customer_id — идентификатор пользователя в системе мерчанта;
   • project_id — идентификатор проекта, полученный от JetPay при интеграции;
   • amount — сумма оплаты в дробных единицах валюты без десятичной точки и пробелов за исключением случаев, когда у валюты нет дробной части. Если у валюты нет дробных единиц (то есть количество разрядов дробных единиц равно нулю), то в этом параметре нужно указывать сумму в основных единицах валюты. Подробнее о разрядах дробных единиц у валют см. Коды валют;
   • currency — валюта платежа в формате ISO-4217 alpha-3;
   • payment_method — идентификатор платежной группы, значение параметра всегда kassa24_bvu;
   • signature — подпись запроса (подробнее — в разделе Использование подписи к данным).

   Рис.: Пример запроса на получение идентификатора платежа на стороне веб-сервиса

   {
      "type": "check_deposit",
      "project_id": 111,
      "customer_id": "johndoe@example.com",
      "amount": 10000,
      "currency": "KZT",
      "payment_method": "kassa24_bvu",
      "signature": "lY0LTSAzpR7...dOqRXJnL1kO0lUmkQ0YYLWRg=="
   }

3. Ответ на запрос check_deposit должен отправляться синхронно и содержать следующие обязательные параметры:
   • code — код ответа на запрос;
   • payment_id — уникальный идентификатор платежа на стороне веб-сервиса.

   Табл. 2. Допустимые коды ответов

   Код	Описание
   0	Операция успешна
   400	Ошибка подписи
   404	Лицевой счет пользователя не существует
   500	Общая ошибка, причина должна быть описана в необязательном параметре error_description

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

   • error_description — описание ошибки;
   • description — описание платежа;
   • customer_id — идентификатор пользователя.

   Успешный ответ на запрос получения идентификатора платежа на стороне веб-сервиса должен содержать код ответа на запрос и уникальный идентификатор платежа на стороне веб-сервиса.

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

   { 
      "code": 0,
      "payment_id": "Asfdsaf3252345",
      "description": "Test payment via terminal"
   }

   Ответ об ошибке получения идентификатора платежа на стороне веб-сервиса должен содержать код ответа на запрос и сообщение об ошибке.

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

   { 
      "code": 500,
      "error_description": "Something went wrong"
   }

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

Для оповещений о результате оплаты с применением метода Kassa24 Terminal BVU используется стандартный формат, описание которого представлено в разделе Оповещения (callbacks) в Gate.

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

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "kassa24_bvu",
        "sum": {
            "amount": 10000,
            "currency": "KZT"
        },
        "description": ""
    },
    "account": {
        "number": "123456"
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "created_date": "2022-03-25T11:08:05+0000",
        "request_id": "9e32835fb27907e0b08569d7d150e387a16a80e336c5117242b5cf60a4e17839",
        "sum_initial": {
            "amount": 10000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "KZT"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

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

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

• Общий порядок интеграции
• Подписывание и проверка подписи
• Типы платежей, операции и платежи
• Статусы операций и коды ответов

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

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

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

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

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