QIWI Kazakhstan

Overview

QIWI Kazakhstan is payment method that allows you to process payments by using e-wallets and kiosks. You can perform purchases through this method by using Gate, payouts by using Gate.

Download the logo in vector format here.
Payment method type
  • E-wallets
  • Kiosks
Countries and regions Kazakhstan
Payment currencies KZT
Currency conversion
Purchases
Payouts
COF payments
Full refunds
Partial refunds
Chargebacks
Notes

For e-wallets, it is possible to make only payments with no invoices to the benefit of specific merchants.
Onboarding and access fee Refer to your key account manager at JetPay

Interaction diagram

Payment processing by using the QIWI Kazakhstan payment method requires merchant's web service, one of JetPay interfaces, and the JetPay payment platform, as well as QIWI Kazakhstan service.

Figure: Interaction diagram for purchase and payout by using Gate



Figure: Interaction diagram for purchase by using QIWI Kazakhstan kiosks and e-wallets



Operations support

  Interfaces Amounts, KZT Times
Payment Page CMS Plug-ins Gate Dashboard minimum maximum basic threshold
Purchases * 30 days
Payouts * 24 hours

* Refer to your key account manager at JetPay for details.

You can check the payment amount limits in your project by using Dashboard. To check your payment amount limits, go to Dashboard, select the Projects section and click the Payment methods tab.

Processing scenarios

To perform a purchase operation in the QIWI Kazakhstan method, you need to have the customer to pay by using QIWI Kazakhstan kiosk, while to initiate a payout, you need to notify customer via merchant's web service.

Figure: Purchase by using Gate via kiosk or e-wallet



Figure: Payout by using Gate



The sections that follow provide detailed information about what you need to perform payments and how you can analyze the information on payments and operations.

Purchase by using Gate via kiosk

General information

In the QIWI Kazakhstan method, when processing a purchase by using Gate, the merchant web service is required to do the following:

  1. Process request for checking customer account existence.
  2. Send information about customer account existence.
  3. Process request for receiving payment identifier on the web service side.
  4. Send payment identifier.
  5. Get the callback with the payment result from the payment platform.

The following diagram provides the detailed picture of the payment processing procedure.



Figure: Purchase sequence by using Gate via kiosk

  1. Customer selects a web service, the personal account in which he wants to replenish, and then enters his credentials in the merchant system.
  2. The kiosk sends request for checking customer account existence to the specified JetPay URL.
  3. The payment platform performs the initial request processing that includes validation of the required parameters and signature.
  4. The payment platform sends request for checking customer account existence to the web service.
  5. The request is processed on the web service side.
  6. The web service sends response to the request.
  7. The payment platform sends customer account data to the QIWI Kazakhstan service.
  8. The QIWI Kazakhstan payment form is displayed to the customer.
  9. The customers pays by cash to replenish personal account.
  10. The payment is processed on the QIWI Kazakhstan side.
  11. The QIWI Kazakhstan service sends the payment result notification to the payment platform.
  12. The payment platform sends request to the web service for payment identifier on the web service side.
  13. The request is processed on the web service side.
  14. The web service sends payment identifier to the payment platform.
  15. Operation is created on the payment platform side.
  16. The payment platform sends the callback to the web service.
  17. The customer receives the payment result on the kiosk screen.

The sections that follow discuss in more details the request format and the Gate parameters to use in the QIWI Kazakhstan payment method and provide the information on the format of callbacks with purchase results.

Request format

There are several things you must consider when using requests for checking account existence in the QIWI Kazakhstan method:

  1. The verify request for checking account existence is sent by using HTTP method POST to the specified web service URL.
  2. The request contains the following required parameters:
    • type—operation type on the web service side, value is always verify
    • customer_id—customer identifier on the web service side
    • project_id—the project ID obtained from JetPay
    • signature—signature created after you specify all the required parameters

    Figure: Example of a request for checking account existence

    {
   "type":"verify",
   "project_id":111,
   "customer_id":"johndoe@example.com",
   "signature":"lY0LT8AzpR7zGce5qfYGacOuYlHGWqkMcQlqmjlsDDZI2gVcE1qVeWANnkIR7mdOqRXJnL1kO0lUmkQ0YYLWRg=="
}
  3. Response to the verify request must be synchronously sent and contain the following required parameters:
    • code—response code
    • currency—currency in the ISO-4217 alpha-3 format
    Table 1. Allowed response codes
    Code Description
    0 Successful operation
    400 Signature is invalid
    404 Account does not exist
    500 General error. The reason should be specified in the message parameter

    Figure: Example of the response

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

There are several things you must consider when using requests for payment identifier on the web service side:

  1. The check_deposit request for payment identifier is sent by using HTTP method POST to the specified web service URL.
  2. The request contains the following required parameters:
    • type—operation type on the web service side, value is always check_deposit
    • customer_id—customer identifier on the web service side
    • project_id—the project ID obtained from JetPay
    • 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—currency in the ISO-4217 alpha-3 format
    • payment_method—payment method name, value is always qiwi-kz;
    • signature—signature created after you specify all the required parameters

    Figure: Example of a request for payment identifier

    {
   "type":"check_deposit",
   "project_id":111,
   "customer_id":"johndoe@example.com",
   "amount":10000,
   "currency":"KZT",
   "payment_method":"qiwi-kz",
   "signature":"lY0LTSAzpR7zGce5qfYGacOuYlHGWqkMcQlqmjlsDDZI2gVcE1qVeWANnkIR7mdOqRXJnL1kO0lUmkQ0YYLWRg=="
}
  3. Response to the check_deposit request must be synchronously sent and contain the following required parameters:
    • code—response code
    • payment_id—payment ID unique within the project
    Table 2. Allowed response codes
    Code Description
    0 Successful operation
    400 Signature is invalid
    404 Account does not exist
    500 General error. The reason should be specified in the message parameter

    Figure: Example of the response

    {
   "code":0,
   "payment_id":"Asfdsaf3252345"
}

Callback format

The QIWI Kazakhstan method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks in Gate.

The following is the example of a callback with an information about successful 20.00 KZT purchase made by the user9876 customer in the 238 project.

Figure: Example of a successful purchase callback

{
        "project_id": 238,
        "payment": {
            "id": "1554967098",
            "type": "purchase",
            "status": "success",
            "date": "2019-04-11T07:18:20+0000",
            "method": "Qiwi Kz Kiosk",
            "sum": {
                "amount": 2000,
                "currency": "KZT"
            },
            "description": ""
        },
        "account": {
            "number": "user9876"
        },
        "operation": {
            "id": 36425000001206,
            "type": "sale",
            "status": "success",
            "date": "2019-04-11T07:18:20+0000",
            "created_date": "2019-04-11T07:18:19+0000",
            "request_id": "25f3114242a16ab1e010ebab4fe816b9d105ff33b90281",
            "sum_initial": {
                "amount": 2000,
                "currency": "KZT"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "KZT"
            },
            "provider": {
                "id": 1197,
                "payment_id": "999990000001a1",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "HRcDJN84ghAJL2hPW9yUbVMm7SRPewQJuH+mz4gcipXc8sI
                         dToQunzSUEiy7w5vA3+MVIO8xHSNsQB5qCCm5kXA=="
    }
}

Related topics

The following topics might be useful when implementing payments through Gate:

Purchase by using Gate via e-wallet

General information

In the QIWI Kazakhstan method, when processing a purchase by using Gate, the merchant web service is required to do the following:

  1. Process the request to check whether the customer account exists .
  2. Respond with the information whether the customer account exists.
  3. Process request for payment identifier on the web service side.
  4. Respond with the payment identifier.
  5. Accept the callback with the payment result from the payment platform.

The following diagram provides the detailed picture of the payment processing procedure.



Figure: Workflow for processing purchase with e-wallet by using Gate

  1. Customer opens QIWI Kazakhstan e-wallet app, selects merchant account to credit, and then enters amount and initiates payment.
  2. E-wallet sends a request for checking whether customer account exists to the JetPay URL.
  3. The payment platform performs the initial request processing that includes validation of the required parameters and signature.
  4. The payment platform sends request for checking customer account existence to the web service.
  5. The web service processes the request.
  6. The web service sends the response to the payment platform.
  7. The payment platform sends customer account data to the QIWI Kazakhstan service.
  8. The QIWI Kazakhstan payment form is displayed to the customer.
  9. The customer uses the QIWI e-wallet to credit personal account.
  10. The QIWI Kazakhstan service processes the request.
  11. The QIWI Kazakhstan service sends purchase outcome information to the payment platform.
  12. The payment platform sends request for payment identifier to the web service.
  13. The web service processes the request.
  14. The web service sends payment identifier to the payment platform.
  15. The operation is created in the payment platform.
  16. The payment platform sends the payment outcome information to the web service.
  17. The payment outcome information is displayed to the customer on the e-wallet .

The sections that follow discuss in more details the request format and the Gate parameters to use in the QIWI Kazakhstan payment method and provide the information on the format of callbacks with purchase results.

Request format

There are several things you must consider when using purchase requests in the QIWI Kazakhstan method:
  1. The verify request to check for the account existence is sent by using HTTP method POST to the web service URL.
  2. The following required parameters must be specified in any request:
    • type—operation type on the web service side, value is always verify
    • customer_id—customer identifier on the web service side
    • project_id—the project ID obtained from JetPay
    • signature—signature created after you specify all the required parameters

    Figure: Example of a request to check for the account existence

    {
   "type":"verify",
   "project_id":111,
   "customer_id":"johndoe@example.com",
   "signature":"lY0LT8AzpR7zGce5qfYGacOuYlHG...kIR7mdOqRXJnL1kO0lUmkQ0YYLWRg=="
}
  3. Response to the verify request must be sent synchronously and contain the following required parameters:
    • code—response code
    • currency—currency in the ISO-4217 alpha-3 format
    Table 3. Allowed response codes
    Code Description
    0 Successful operation
    400 Signature is invalid
    404 Account does not exist
    500 General error. The reason can be specified in an optional message parameter.

    Figure: Example of the response the verify request

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

There are several things you must consider when using requests for payment identifier on the web service side:

  1. The check_deposit request for payment identifier in the web service is sent to the web service URL by using HTTP method POST.
  2. The request contains the following required parameters:
    • type—operation type on the web service side, value is always check_deposit
    • customer_id—customer identifier assigned by the web service
    • project_id—the project ID obtained from JetPay
    • 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—currency in the ISO-4217 alpha-3 format
    • payment_method—payment method name, value is always qiwi-kz;
    • signature—signature created after you specify all the required parameters

    Figure: Example of a request for payment identifier assigned by the web service

    {
   "type":"check_deposit",
   "project_id":111,
   "customer_id":"johndoe@example.com",
   "amount":10000,
   "currency":"KZT",
   "payment_method":"qiwi-kz",
   "signature":"lY0LTSAzpR7zGce5qfYGacOuYlHGWqkMcQl...Q0YYLWRg=="
}
  3. Response to the check_deposit request must be sent synchronously and contain the following required parameters:
    • code—response code
    • payment_id—payment ID unique within the project
    Table 4. Allowed response codes
    Code Description
    0 Successful operation
    400 Signature is invalid
    404 Account does not exist
    500 General error. The reason can be specified in an optional message parameter.

    Figure: Example of the response to the check_deposit request

    {
   "code":0,
   "payment_id":"Asfdsaf3252345"
}

Callback format

The QIWI Kazakhstan method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks in Gate.

The following is the example of a callback with an information about successful 20.00 KZT purchase made in the 238 project.

Figure: Example of a successful purchase callback

{
        "project_id": 238,
        "payment": {
            "id": "1554967098",
            "type": "purchase",
            "status": "success",
            "date": "2019-04-11T07:18:20+0000",
            "method": "Qiwi Kz Terminal",
            "sum": {
                "amount": 2000,
                "currency": "KZT"
            },
            "description": ""
        },
        "account": {
            "number": "user9876"
        },
        "operation": {
            "id": 36425000001206,
            "type": "sale",
            "status": "success",
            "date": "2019-04-11T07:18:20+0000",
            "created_date": "2019-04-11T07:18:19+0000",
            "request_id": "25f3114242a16ab1e010ebab4fe816b9d105ff33b90281",
            "sum_initial": {
                "amount": 2000,
                "currency": "KZT"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "KZT"
            },
            "provider": {
                "id": 1197,
                "payment_id": "999990000001a1",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "HRcDJN84ghAJL2hPW9yUbVMm7SRPewQJuH+mz4gcipXc8sI
                         dToQunzSUEiy7w5vA3+MVIO8xHSNsQB5qCCm5kXA=="
    }
}

Related topics

The following topics might be useful when implementing payments through Gate:

Payout by using Gate

General information

To perform a payout through the QIWI Kazakhstan method, merchant's web service sends a request with all the required parameters and signature to JetPay URL, and receives a callback with the payment result. The full sequence of the payout process is provided below.



Figure: Payout sequence by using Gate

  1. A customer orders a payout through the QIWI Kazakhstan service.
  2. Merchant's web service sends the request for processing the payout through Gate to the appropriate JetPay URL.
  3. Gate redirects the request to the JetPay payment platform.
  4. The payment platform performs all the necessary check and processes the request.
  5. The reply with the request processing results is sent to the merchant's web service. For more information, see Response structure.
  6. The payment platform redirects the payout request to the QIWI Kazakhstan service.
  7. The payout is processed on the QIWI Kazakhstan side.
  8. QIWI Kazakhstan sends the result notification to the payment platform.
  9. The payment platform sends a callback with the payment result to the web service.
  10. The customer receives the payout result from the web service.

The sections that follow discuss in more details the request format and the Gate parameters to use in the QIWI Kazakhstan payment method and provide the information on the format of callbacks with payout results.

Request format

There are several things you must consider when using payout requests in the QIWI Kazakhstan method:
  1. You perform payouts by sending the /v2/payment/wallet/qiwi-kz/payout request by using POST (HTTP) method. This is an e-wallets request group: /v2/payment/wallet/{payment_method}/payout.
  2. The following objects and parameters must be specified in any request:
    • general—object with general request identification information:
      • project_id—the project ID obtained from JetPay
      • payment_id—payment ID unique within the project
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
    • customer—object with customer information:
      • id—the unique ID of the customer within your project
      • ip_address—IP address of the customer's device
      • first_name—customer first name
      • last_name—customer last name
      • email—customer email
    • account—object with customer account information:
      • number—customer account number
    • payment—object with payout information:
      • amount—payout 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 payout currency in the ISO-4217 alpha-3 format
  3. The currency of payout can only be KZT.
  4. If required, you can also add any other additional parameters Gate supports.

Here is an example of data from a payout request in the QIWI Kazakhstan method.

Figure: Example of a payout request 

{
    "general": {
        "project_id": 35,
        "payment_id": "test_123",
        "signature": "kUi2x9dKHAVNU0FY"
    },
    "customer": {
        "ip_address": "198.51.100.47",
        "id":"12345",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "account": {
        "number": "9182221133"
    },
    "payment": {
        "amount": 100,
        "currency": "KZT"
    }
}

Callback format

The QIWI Kazakhstan method uses the standard format for callbacks to deliver payout results. For more information, see Callbacks in Gate.

The following is the example of a callback with an information about successful 100.00 KZT payout.

Figure: Example of data from a successful payout callback

{
    "project_id": 1234,
    "payment": {
        "id": "payment_48",
        "type": "payout",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "qiwi-kz",
        "sum": {
            "amount": 10000,
            "currency": "KZT"
        },
        "description": ""
    },
    "operation": {
        "id": 29,
        "type": "payout",
        "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-123",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

The following is the example of a callback for a declined payout.

Figure: Example of data from a declined payout callback

{
    "project_id": 1234,
    "payment": {
        "id": "payment_48",
        "type": "payout",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "method": "qiwi-kz",
        "sum": {
            "amount": 10000,
            "currency": "KZT"
        },
        "description": ""
    },
    "operation": {
        "id": 29,
        "type": "payout",
        "status": "decline",
        "date": "2022-03-25T11:20:30+0000",
        "created_date": "2022-03-25T11:19:53+0000",
        "request_id": "fff3d5f8d5d31bc460b68b57dc63f4b482e906eb",
        "sum_initial": {
            "amount": 10000,
            "currency": "KZT"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "KZT"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "J7W15rkqrLzTCD4HkoM4qoEnlVlf155QSlXJKR4m8C4z2iFYv58P4VnHANu445/jmY+g=="
}

Related topics

The following topics might be useful when implementing payments through Gate:

Payout by using Dashboard

To make a payout through Dashboard, the merchant sends a request and receives a notification with the request processing result. There are two ways to initiate payouts through Dashboard:
  • single payout—you specify the currency and amount for a payout available for this method and fill in all the fields required for the selected payment method on the Dashboard pages.
  • as a part of a mass payment—all the parameters are specified in a CSV file. Refer to the Payouts by using Gate section for the parameters required by your payment method.

Information about completed payouts is available for viewing in the Payments and Manual Payments sections of Dashboard.

For more information about payout processing by using Dashboard, see Performing payouts.

Analysis of payments results

As with other payment methods JetPay offers, when using this method, you have several options to analyze the information about payments and operations.

You can load and analyze all the necessary information in Dashboard (dashboard.jetpay.kz), for instance you can use the analytic panels in the Analytics section for this purpose.

Also, you can export the information for further analysis by using third party analytical tools. The following options are available:

  • Dashboard allows you to download reports in CSV format by using the tools in the Reports section. You can perform export as a one-time or regular download of data to your local computer.
  • Data API allows you to have payment information exported in JSON format and delivered to a URL you specify. The payment information is exported by means of sending requests to the /operations/get endpoint.

If you have any further questions regarding payment data analysis, contact JetPay technical support.