Kassa24 Terminal

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

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

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

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

3. Ответ на запрос verify должен отправляться синхронно. Доступны два варианта ответа, уточняйте у вашего курирующего менеджера JetPay, какой подходит вам.
   Первый вариант ответа должен содержать следующие параметры:

   • code — код ответа на запрос (допустимые значения указаны в таблице ниже);
   • currency — валюта платежа в формате ISO-4217 alpha-3.

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

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

   Второй вариант ответа должен содержать следующие параметры:

   • code — код ответа на запрос;
   • additional_customer_id — идентификатор пользователя, уникальный в рамках проекта, который используется для идентификации пользователя в платежной платформе JetPay;
   • currency — код валюты платежа в формате ISO-4217 alpha-3;
   • entities.id — идентификатор договора;
   • entities.number — номер договора;
   • entities.payment — сумма оплаты в дробных единицах валюты без десятичной точки и пробелов за исключением случаев, когда у валюты нет дробной части. Если у валюты нет дробных единиц (то есть количество разрядов дробных единиц равно нулю), то в этом параметре нужно указывать сумму в основных единицах валюты. Подробнее о разрядах дробных единиц у валют см. Коды валют. Обязательность этого параметра уточняйте у курирующего менеджера JetPay;
   • entities.status_code — код статуса договора. Значение по умолчанию 0 - онлайн оплата разрешена, значение отличное от 0 не позволяет принять оплату, но позволит отобразить клиенту заранее согласованный текст при выборе договора к оплате. Дополнительные коды и сообщения согласовываются индивидуально, уточняйте у курирующего менеджера JetPay.

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

   • error_description — произвольное описание ошибки от мерчанта;
   • customer_name — полное имя пользователя;
   • entities.date — дата заключения договора.

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

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

   Вот пример ответа на запрос, если лицевой счет пользователя существует в вашей системе.

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

   {
       "code": 0,
       "currency": "KZT",
       "additional_customer_id": "ABCDE12345",
       "error_description":"example"
   }

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

   {
       "code": 0,
       "currency": "KZT",
       "customer_name": "John Doe",
       "additional_customer_id": "ABCDE12345",
       "entities": [
           {
               "id": "12345",
               "number": "1234_ABC/01-01-2025/Abcdef12",
               "date": "2026-04-01",
               "payment": 100000,
               "status_code": 0
           },
           {
               "id": "67890",
               "number": "5678_ABC/01-01-2025/Abcdef34",
               "payment": 0,
               "status_code": 204
           }
       ]
   }

   Если запрос нельзя корректно обработать или не удалось обнаружить запрошенный лицевой счет, ответ на запрос должен содержать код ответа 404, а также может содержать дополнительную информацию об ошибке в параметре message.

   Рис.: Пример ответа с кодом ошибки

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

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

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

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

   • number — номер договора, по которому выполняется оплата;
   • entity_id — идентификатор договора, по которому выполняется оплата;

   Рис.: Пример данных из запроса на получение идентификатора платежа в вашей системе

   { 
      "type": "check_deposit",
      "project_id": 1234,
      "customer_id": "123456789",
      "entity_id": "12345",
      "number": "1234_ABC/01-01-2025/Abcdef12",
      "amount": 10 000,00,
      "currency": "KZT",
      "payment_method": "kassa24",
      "signature": "lY0LTSAzpR7zGce5qfYGacOuYlHANnkIR7mdOqRXJnL1kO0lUmkQ0YYLWRg=="
   }

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

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

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

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

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

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

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

   {
       "code": 0,
       "payment_id": "payment_47",
       "description": "Success"
   }

   Ответ c информацией об ошибке должен содержать код ответа на запрос и сообщение об ошибке.

   Рис.: Пример ответа с информацией об ошибке

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