Bank Transfers (Kaspi Bank)

Kaspi Bank Payments Interaction Diagram

Kaspi Bank payment interaction diagram description:

User logs into the Kaspi Bank app, selects the Partner's service to make a payment and enters the account details in the Partner's system (phone number)
Kaspi Bank sends a request to verify the possibility of replenishment to the System Gateway.
The System validates the received request for correct structure, required parameters, etc. and generates a request to verify the possibility of replenishing the User's account in the Partner's service.
The Partner processes the received request, checks the availability of the User's account in their system and the ability to make a deposit. In response, the Partner returns the status confirming the possibility of replenishment or its absence, for example:
• YES – The user exists, so the payment can proceed;
• NO – The user does not exist, so the payment cannot be processed;
• ERROR – An error occurred while processing the request.
The system processes the Partner's response and returns the corresponding response to Kaspi Bank.
Kaspi Bank notifies the end User about the possibility/impossibility of making a deposit to the account in the Partner's service.
There can be as many requests for user verification as needed, at this stage the payment itself is not formed at this stage, both on the side of Kaspi Bank and in the information exchange between all parties.
The User enters the payment amount and accepts payment in Kaspi Bank app, meanwhile bank holds an entered amount on User’s bank account and sends a payment request to the System Gateway.
The System accepts a payment request, registers it and forms a request to credit funds to the User's account in the Partner's service.
The Partner's Service accepts the incoming payment, processes it, and credits funds to the User's account in its service.
In response, the Partner returns the result of processing the payment and crediting funds to the User's account in the service, for example:
• YES – Funds were credited to the account successfully (the payment was successful);
• NO – Funds cannot be credited to the User's account (or the payment is not successful);
• ERROR – Other errors while processing the incoming request.
The system processes the received response from the Partner, records the result of the payment and returns a response to Kaspi Bank about the success or failure of the payment.
Kaspi Bank debits funds from the User (or, in case of an unsuccessful payment, unholds them in the User's bank account) and notifies the User of the success/failure of the payment.
The System notifies the Partner about the successful debiting of funds for the operation.
The Partner processes the notification and returns a response on successful receipt to the System.

Requirements for Interaction between Partner and System Organization

Information is exchanged between systems in JSON format.
Messages are sent over HTTPS using the POST method to the Partner service request processing server.
Request headers must include an authorization parameter for the Partner's system, using the MD5-Hash authorization algorithm (headers: sign).

Request to Verify the Possibility of Adding Funds to the User's Account

Upon receiving a request from Kaspi Bank, the System generates a request to verify the User with the Partner's service:

POST request to {{url_partner}}

Where {{url_partner}} is the URL of the Partner Service that handles incoming requests.

Main Header Parameters

Parameter	Required	Type	Description	Example
Content-Type	Yes	String	Data type of the request content	`application/json`
sign	Yes	String	Request verification signature, MD5 hash (`account + secret_key`), where `+` is the concatenation sign and `secret_key` is generated by the Partner.	`dd32ecdcef74640cad316dc8b24c83c1`

Request Parameters

Parameter	Required	Type	Description	Example
account	Yes	String	User’s account ID in the Partner’s service	`79012345678`

Partner’s Response Parameters Description

Parameter	Required	Type	Description	Example
iin	No	String	The User's Individual Identification Number (IIN)	`90749075042905`
status	Yes	String	Request processing result: • `YES` – User exists (payment is possible); • `NO` – User does not exist (payment is not possible); • `ERROR` – Other errors while processing the incoming request.	`YES`

API Reference

You can view a Reference API implementation for this method at this link

Request to Add Funds to the User's Account in the Partner's Service

Upon receiving a request from Kaspi Bank, the System generates a request to replenish the User's account in the Partner's service:

POST request to {{url_partner}}

Where {{url_partner}} is the URL of the Partner Service that handles incoming requests.

Main Header Parameters

Parameter	Required	Type	Description	Example
Content-Type	Yes	String	Data type of the request content	`application/json`
sign	Yes	String	Request verification signature: MD5 hash (`operationId + account + amount + currency + secret_key`), where `+` is the concatenation sign and `secret_key` is generated by the Partner.	`f58a18b507f827e019aa3e6e9609463e`

Request Parameters

Parameter	Required	Type	Description	Example
account	Yes	String	User’s Account ID in the Partner's service	`79012345678`
operationId	Yes	String	Unique Kaspi Bank payment operation identifier	`2000284500`
amount	Yes	String	Payment amount. Format: positive floating-point number with "." as the delimiter; up to 2 decimal places	`100.00`
currency	Yes	String	Payment currency (debit)	`KZT`

Partner’s Response Parameters Description

Parameter	Required	Type	Description	Example
transactionId	No	String	Unique number of the registered payment transaction in the Partner's service (required if `status` = `YES`)	`33`
status	Yes	String	Payment processing result: • `YES` – Funds were successfully credited to the account (payment successful); • `NO` – Funds cannot be credited to the User's account (payment unsuccessful); • `ERROR` – Other errors occurred while processing the request.	`YES`

API Reference

You can view a Reference API implementation for this method at this link

Successful Payment Notification

Upon receiving a request from Bank, the System generates a notification to confirm the addition of funds to the User's account in the Partner's service:

POST request to {{url_partner}}

Where {{url_partner}} is the URL of the Partner Service that processes incoming requests.

Main Headers Parameters

Parameter	Required	Type	Description	Example
Content-Type	Yes	String	Data type of the request content	`application/json`
sign	Yes	String	Request verification signature: MD5 hash (`operationId + account + amount + currency + secret_key`) where `+` is the concatenation sign and `secret_key` is generated by the Partner.	`b1958a276310bf28929d0b2c54f31300`

Request Parameters

Parameter	Required	Type	Description	Example
account	Yes	String	User’s Account ID in the Partner's service	`79012345678`
operationId	Yes	String	Unique Kaspi Bank payment operation identifier	`2000284500`
amount	Yes	String	Payment amount. Format: positive floating-point number with "." as the delimiter; up to 2 decimal places	`100.00`
currency	Yes	String	Payment currency (debit)	`KZT`
transactionId	Yes	String	Unique payment ID in the Partner's service	`33`
status	Yes	String	Payment status in the System: • `completed` – the payment was successfully processed in the System	`completed`

Important: In response to the notification, the System expects the Partner's service to return an HTTP status code of 200 OK. If a different response or HTTP code is received, the System will continue to resend the request until the payment status is successfully confirmed.

API Reference

You can view a Reference API implementation for this method at this link