Kassa24 Terminal

There are several things you need to consider when dealing with account top up requests in the Kassa24 Terminal method:

1. To verify the existence of the customer account, the payment platform sends the verify request to your system URL using the HTTP method POST.
2. The request has the following parameters:
   • type—the operation type in your system (always verify)
   • customer_id—customer account ID in your system used for topping up from the customer account
   • project_id—the project ID you obtained from JetPay
   • signature—the signature for the request.

   Figure: Example of the data from the request for verifying the customer account

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

3. You need to send the response to the verify request synchronously. There can be two response options, confirm with your JetPay key account manager, which one is suitable for you.

   Response option 1 must contain the following parameters:

   • code—response code (available codes are listed in the table below)
   • currency—currency code in the ISO-4217 alpha-3 format

   Your response can contain the following additional parameters:

   • additional_customer_id—customer ID on your system's side, which is used for customer identification on the JetPay side
   • error_description—user-friendly error description
   Response option 2 must contain the following parameters:
   • code—the response code
   • additional_customer_id—the unique customer ID used for the customer identification in the JetPay payment platform.
   • currency—the code of the purchase currency in the ISO-4217 alpha-3 format
   • entities.id—contract ID
   • entities.number—contract number for topping up
   • entities.payment—purchase amount in minor currency units without any decimal point or comma except for cases where the currency does not have any minor currency units. If the currency has no minor units (that is, the number of digits for minor currency units is zero), then you must set this parameter to the amount in the major currency units. For the information on whether the currency has any minor units, see Currency codes. The parameter may not be required in some cases. Contact your account manager at JetPay for details.
   • entities.status_code—contract status code. The default value is 0—online payment is allowed. A value other than 0 does not allow the payment to be accepted, but will allow the customer to see a preset text when selecting a contract for payment. Additional codes and messages are agreed upon individually, contact your JetPay key account manager for details.

   Your response can contain the following additional parameters:

   • message—the free-form description of the response code
   • entities.info—an object with an arbitrary set of fields, used to display additional information to the customer. The structure is customizable, refer to your JetPay key account manager for more information.
   • entities.min_payment—minimum allowed purchase amount in minor currency units without any decimal point or comma except for cases where the currency does not have any minor currency units. If the currency has no minor units (that is, the number of digits for minor currency units is zero), then you must set this parameter to the amount in the major currency units. For the information on whether the currency has any minor units, see Currency codes.

   Table 1. Applicable response codes

   Code	Description
   0	Success
   204	No outstanding debts found
   400	Signature error
   404	The customer account does not exist
   500	General error, the reason must be specified in the message parameter

   Here's an example of a response when the existence account verification is successful.

   Figure: Example of the request response for the first option

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

   Figure: Example of the request response for the second option

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

   If the request cannot be processed or the requested account is not found, the response should contain the 404 response code and the error description in the message parameter.

   Figure: Example of the request response with an error

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

There are several things you need to consider when dealing with requests for the transaction ID:

1. The payment platform sends the check_deposit request for the transaction ID to your system URL using HTTP method POST.
2. The request contains the following parameters:
   • type—the operation type in your system (always check_deposit)
   • project_id—the project ID you obtained from JetPay
   • customer_id—customer account ID in your system used for topping up from the customer account
   • amount—purchase amount in minor currency units without any decimal point or comma except for cases where the currency does not have any minor currency units. If the currency has no minor units (that is, the number of digits for minor currency units is zero), then you must set this parameter to the amount in the major currency units. For the information on whether the currency has any minor units, see Currency codes
   • currency—code of purchase currency in the ISO-4217 alpha-3 format
   • payment_method—the payment ID. The value of the parameter is always kassa24
   • signature—the signature for the request.

   The following parameters are only necessary with the second verify response option:

   • entity_id—contract ID for topping up
   • number—contract number for topping up

   Figure: Example of the request for the transaction ID on your system's side

   { 
      "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. You must respond to the check_deposit request synchronously. There can be two response options, confirm with your JetPay key account manager, which one is suitable for you.

   Response option 1 must contain the following parameters:

   • code—response code
   • payment_id—payment ID unique on your system's side

   Response may also contain the following optional parameters:

   • error_description—user-friendly error description
   • description—payment description
   • customer_id—customer ID

   Response option 2 must contain the following parameters:

   • code—the response code
   • payment_id—the payment ID unique in your system. This parameter is required for the response with code 0

   Your response can have the following additional parameters:

   • message—the free-form description of the response code
   • description—the description of the payment

   Table 2. Applicable response codes

   Code	Description
   0	Success
   400	Signature error
   404	The customer account does not exist
   500	General error, the reason must be specified in the message parameter

   The response to the request for the transaction ID in your system must contain the response code and the unique transaction ID.

   Figure: Example of the response with the transaction ID

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

   If the transaction ID cannot be found, the response must contain the response code and the error description in the message parameter.

   Figure: Example of the response with the information about an error

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