Kaspi Bank

There are several things you need to consider when dealing with account top up requests in the Kaspi Bank 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. The response 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. This parameter is required for the response with code 0
   • currency—the code of the purchase currency in the ISO-4217 alpha-3 format.
   • entities.id—contract ID. This parameter is required for the response with code 0
   • entities.number—contract number for topping up. This parameter is required for the response with code 0
   • 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.

   Table 1. 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

   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.

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

   Figure: Example of the request response

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

   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
   • entity_id — contract ID for topping up
   • 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 terminal/kaspi
   • signature—the signature for the request.

   Figure: Example of the request for the transaction ID on the web service side

   { 
      "type": "check_deposit",
      "project_id": 1234,
      "customer_id": "123456789",
      "entity_id": "12345",
      "amount": 10000,
      "currency": "KZT",
      "payment_method": "terminal/kaspi",
      "signature": "lY0LTSAzpR7zGce5qfYGacOuYlHANnkIR7mdOqRXJnL1kO0lUmkQ0YYLWRg=="
   }

3. You must respond to the check_deposit request synchronously. The response 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

   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

   Your response can have the following additional parameters:

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

   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"
   }