Purchases via Mbank bank accounts

Overview

Introduction

Purchases via Mbank bank accounts is a payment method which allows you to process payments in Kyrgyz som by using online banking in Kyrgyzstan. This method supports purchases.

This article provides information about working with the Purchases via Mbank bank accounts method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

General information

Payment method type bank payments
Payment instruments bank accounts
Countries and regions KG
Payment currencies KGS
Currency conversion –
One-time purchases +
Credential-on-file purchases –
Full refunds –
Partial refunds –
Payouts –
Chargebacks –
Notes –
Onboarding and access fee refer to your Flashpay account manager

Interaction diagram

Payment processing by using the Purchases via Mbank bank accounts method involves the merchant's web service, one of Flashpay interfaces, the Flashpay payment platform, and technical facilities of the Mbank service.

Operations support

Various platform interfaces can be used to process payments and perform operations using the Purchases via Mbank bank accounts method. Purchases can be processed by using Payment Page, Gate and Dashboard (using payment links). At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

The following properties and limitations apply to the Purchases via Mbank bank accounts method.

Amounts, KGS Times ¹
minimum maximum base threshold
Purchases 50.00 50,000.00 1 minute 60 minutes
Note:
  1. The base and threshold times are defined as follows:
    • The base time is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour (if any input from the customer is required). Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status (details).
    • The threshold time is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the decline status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Flashpay technical support.

Processing scenarios

To perform a purchase by using the Purchases via Mbank bank accounts method, you need to redirect the customer to the Mbank service.

Figure 1. Purchase by using Payment Page
Figure 2. Purchase by using Gate

Purchases by using Payment Page

General information

To process a purchase through Payment Page by using the Purchases via Mbank bank accounts method, the merchant's web service is required to send a request with all required parameters and signature to the Flashpay URL and receive a callback with the result.

Figure 3. Purchase processing by using Payment Page: step-by-step description
  1. A customer initiates a purchase in the web service.
  2. The web service sends the request for opening Payment Page to the specified Flashpay URL.
  3. The request for opening Payment Page is sent to the payment platform.
  4. The payment platform receives the request and validates the required parameters and signature.
  5. Payment Page is generated based on the project and request parameters.
  6. Payment Page is displayed to the customer.
  7. The customer selects the Purchases via Mbank bank accounts method and specifies the phone number associated with the bank account.
  8. The payment platform receives the request for processing the payment by using the Purchases via Mbank bank accounts method.
  9. The payment platform processes the request and sends it to the Mbank service.
  10. The request is processed on the Mbank service side.
  11. The Mbank service sends the information about the necessity to confirm the payment using the payment confirmation code to the payment platform.
  12. The payment platform sends the information about the necessity to confirm the payment using the payment confirmation code to Payment Page.
  13. The confirmation code input form is displayed to the customer on Payment Page.
  14. The Mbank service sends the confirmation code to the customer.
  15. The customer enters the confirmation code on Payment Page and confirms the purchase.
  16. The purchase is processed in the Mbank service.
  17. The result information is displayed to the customer in the Mbank service.
  18. The Mbank service sends a notification about the result to the payment platform.
  19. The payment platform sends the payment result callback to the web service.
  20. The payment platform sends the result information to Payment Page.
  21. The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Purchases via Mbank bank accounts method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in Interaction concepts.

Request format

There are several things you need to consider when sending purchase requests by using the Purchases via Mbank bank accounts method:

  1. The following parameters required for any payment must be specified:
    • project_id—project identifier obtained from Flashpay during integration
    • payment_id—payment identifier unique within the project
    • payment_currency—payment currency code in the ISO-4217 alpha-3 format
    • payment_amount—payment amount in the smallest currency unit
    • customer_id—customer identifier unique within the project
  2. The following parameters required for any payment must be specified: project_id, payment_id, payment_currency, payment_amount, customer_id.
  3. If you need to have the payment form displayed with the Purchases via Mbank bank accounts method selected, set the force_payment_method parameter to mbank.
  4. Additionally, any other parameters available for working with Payment Page can be used (details).
  5. After all target parameters are specified, generate a signature (details).

Thus, a correct request for opening the payment form using the Purchases via Mbank bank accounts method must contain the project identifier, basic payment information (identifier, amount, and currency code), customer identifier and signature, as well as possible additional parameters.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "KGS",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}
Figure 4. Example of sufficient data in a purchase request
{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "KGS",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Callback format

The Purchases via Mbank bank accounts method uses the standard format for callbacks to deliver purchase results. For more information, see Handling callbacks (details).

The following is the example of a callback with information about a 50.00 KGS purchase made in the 137493 project.

Figure 5. Example of callback data indicating that the purchase has been processed
{
        "customer": {
            "id": "1"
        },
        "account": {
            "number": "341******554"
        },
        "project_id": 137493,
        "payment": {
            "id": "TEST_PAYMENT_212105",
            "type": "purchase",
            "status": "success",
            "date": "2025-01-27T08:15:24+0000",
            "method": "mbank",
            "sum": {
                "amount": 50000,
                "currency": "KGS"
            },
            "description": "TEST_PAYMENT_212105"
        },
        "operation": {
            "sum_initial": {
                "amount": 5000,
                "currency": "KGS"
            },
            "sum_converted": {
                "amount": 5000,
                "currency": "KGS"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 17101,
                "payment_id": "0194a6d2-ff53-762a-a493-d0f017bd4875",
                "auth_code": ""
            },
            "id": 6503010168993,
            "type": "sale",
            "status": "success",
            "date": "2025-01-27T08:15:24+0000",
            "created_date": "2025-01-27T08:13:50+0000",
            "request_id": "d5156dd4af333bfbfd24ca-00006504"
        },
        "signature": "fXUbnU5Zff/hGskEkG8k2+Gyz3SKcQ=="
    }

The following is the example of a callback with information about a declined purchase.

Figure 6. Example of callback data indicating that the purchase has been declined
{
        "customer": {
            "id": "1"
        },
        "account": {
            "number": "123******432"
        },
        "project_id": 137493,
        "payment": {
            "id": "TEST_PAYMENT_331631",
            "type": "purchase",
            "status": "decline",
            "date": "2025-01-28T10:45:41+0000",
            "method": "mbank",
            "sum": {
                "amount": 5000,
                "currency": "KGS"
            },
            "description": "TEST_PAYMENT_331631"
        },
        "operation": {
            "sum_initial": {
                "amount": 5000,
                "currency": "KGS"
            },
            "sum_converted": {
                "amount": 5000,
                "currency": "KGS"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 17101,
                "payment_id": "0194ac84-0992-7bf3-bd8e-0b1170cc2b8b",
                "auth_code": ""
            },
            "id": 6296010169189,
            "type": "sale",
            "status": "decline",
            "date": "2025-01-28T10:45:41+0000",
            "created_date": "2025-01-28T10:45:18+0000",
            "request_id": "080bc706bb3fa2f3ec4509055e-00006297"
        },
        "signature": "WpWZ+gvMPe9ldONXZEUZpRisl3m+udOyy21XZBYftVTWg=="
    }

Useful links

The following articles can be useful when implementing purchases via Payment Page:

Purchases by using Gate

General information

To process a purchase through Gate by using the Purchases via Mbank bank accounts method, the merchant's web service is required to do the following:

  1. Send a request with all the required parameters and signature to the Flashpay URL.
  2. Receive the additional payment information callback and send the request with the required data to continue the payment. For more details, see Submission of additional payment information.
  3. Receive the final callback from the payment platform.
Figure 7. Purchase processing by using Gate: step-by-step description
  1. A customer initiates a purchase by using the Purchases via Mbank bank accounts method in the web service.
  2. The web service sends the request for processing the purchase by using Gate to the specified Flashpay URL.
  3. The payment platform receives the request.
  4. The payment platform validates the required parameters and signature in the request.
  5. The payment platform sends the response to the web service with information about the receipt of the request and its validity (details).
  6. The payment platform performs further processing of the request (with parameter consistency check) and sends it to the Mbank service.
  7. The request is processed on the Mbank service side.
  8. The Mbank service sends the information about the necessity to confirm the payment using the payment confirmation code to the payment platform.
  9. The payment platform sends the information about the necessity to confirm the payment using the payment confirmation code to the web service.
  10. The web service displays the confirmation code input form to the customer.
  11. The Mbank service sends the confirmation code to the customer.
  12. The customer enters the confirmation code on the web service side and confirms the purchase.
  13. The purchase is processed in the Mbank service.
  14. The result is displayed to the customer.
  15. The Mbank service sends the payment result notification to the payment platform.
  16. The payment platform sends the payment result callback to the web service.
  17. The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Mbank method via Gate is presented further in this section. General information about working with the Gate API is presented in Interaction concepts.

Request format

There are several things you need to consider when sending purchase requests by using the Mbank method:

  1. To initiate each purchase, send a separate POST request to the /v2/payment/wallet/mbank/sale endpoint. This endpoint belongs to the group /v2/payment/wallet/{payment_method}/sale.
  2. Each request must include the following objects and parameters:
    • Object general—general purchase information:
      • project_id—project identifier obtained from Flashpay during integration
      • payment_id—payment identifier unique within the project
      • signature—request signature generated after all required parameters are specified (details—in the Signature generation and verification) (details)
    • Object payment—payment information:
      • amount—payment amount in the smallest currency unit
      • currency—payment currency code in the ISO-4217 alpha-3 format
    • Object customer—customer information:
      • id—customer identifier unique within the project
      • ip_address—customer IP address relevant for the initiated payment
    • Object account—customer account information:
      • number—customer phone number associated with the bank account.
  3. Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Purchases via Mbank bank accounts method must contain the project identifier, basic payment information (identifier, amount, and currency code), customer and account information, signature, as well as possible additional parameters.

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "KGS"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0"
  },
   "account": {
     "number": "189011234567"
  },
}
Figure 8. Example of sufficient data in a purchase request
{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "KGS"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0"
  },
   "account": {
     "number": "189011234567"
  },
}

Format of requests for additional payment information submission

In order to submit additional payment information, the web service needs to receive the appropriate callback from the payment platform, send a POST request with the required information to the /v2/payment/clarification endpoint and receive a 200 OK response from the platform.

The callback contains the clarification_fields object which contains the approval_code parameter—payment confirmation code which the customer specifies on the web service side. The lifespan of the confirmation code is 60 minutes by default (starting when the code is created on the payment platform side). Refer to your Flashpay key account manager to alter the lifespan of the code.

The following example of the callback fragment contains the information which is required to continue the payment.

{
 "clarification_fields": {
      "approval_code"
   }
}

The web service needs to submit the requested additional payment information in a request to the /v2/payment/clarification endpoint by using the POST HTTP method. The request must contain the following objects and parameters:

  • general—object that contains general request identification information:
    • project_id—the project ID which is relevant to the payment
    • payment_id—payment ID which is relevant to the data being sent
    • signature—signature generated after all of the required parameters are specified. For more information about signature generation, see Signature generation and verification.
  • additional_data—object that contains additional payment information that payment platform requests:
    • approval_code—payment confirmation code, which the customer specifies on the web service side.

Thus, a correct request must include project and payment IDs, signature and additional payment information.

{
  "general": {
    "project_id": 11,
    "payment_id": "EPr-bf14",
    "signature": "v7KNMpfogAthg1ZZ5D/aZAeb0VMdeR+CqghwSm...=="
  },
  "additional_data": {
    "approval_code": "1234"
    }
}
Figure 9. Example of sufficient data in a request for submitting additional information
{
  "general": {
    "project_id": 11,
    "payment_id": "EPr-bf14",
    "signature": "v7KNMpfogAthg1ZZ5D/aZAeb0VMdeR+CqghwSm...=="
  },
  "additional_data": {
    "approval_code": "1234"
    }
}
Note: If the code sent in the request is not correct, or the code was not sent within the specified time, the payment is declined.

Final callback format

The Purchases via Mbank bank accounts method uses the standard format for callbacks to deliver purchase results. For more information, see Handling callbacks (details).

The following is the example of a callback with information about a 50.00 KGS purchase made in the 137493 project.

Figure 10. Example of callback data indicating that the purchase has been processed
{
        "customer": {
            "id": "1"
        },
        "account": {
            "number": "341******554"
        },
        "project_id": 137493,
        "payment": {
            "id": "TEST_PAYMENT_212105",
            "type": "purchase",
            "status": "success",
            "date": "2025-01-27T08:15:24+0000",
            "method": "mbank",
            "sum": {
                "amount": 50000,
                "currency": "KGS"
            },
            "description": "TEST_PAYMENT_212105"
        },
        "operation": {
            "sum_initial": {
                "amount": 5000,
                "currency": "KGS"
            },
            "sum_converted": {
                "amount": 5000,
                "currency": "KGS"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 17101,
                "payment_id": "0194a6d2-ff53-762a-a493-d0f017bd4875",
                "auth_code": ""
            },
            "id": 6503010168993,
            "type": "sale",
            "status": "success",
            "date": "2025-01-27T08:15:24+0000",
            "created_date": "2025-01-27T08:13:50+0000",
            "request_id": "d5156dd4af333bfbfd24ca-00006504"
        },
        "signature": "fXUbnU5Zff/hGskEkG8k2+Gyz3SKcQ=="
    }

The following is the example of a callback with information about a declined purchase.

Figure 11. Example of callback data indicating that the purchase has been declined
{
        "customer": {
            "id": "1"
        },
        "account": {
            "number": "123******432"
        },
        "project_id": 137493,
        "payment": {
            "id": "TEST_PAYMENT_331631",
            "type": "purchase",
            "status": "decline",
            "date": "2025-01-28T10:45:41+0000",
            "method": "mbank",
            "sum": {
                "amount": 5000,
                "currency": "KGS"
            },
            "description": "TEST_PAYMENT_331631"
        },
        "operation": {
            "sum_initial": {
                "amount": 5000,
                "currency": "KGS"
            },
            "sum_converted": {
                "amount": 5000,
                "currency": "KGS"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 17101,
                "payment_id": "0194ac84-0992-7bf3-bd8e-0b1170cc2b8b",
                "auth_code": ""
            },
            "id": 6296010169189,
            "type": "sale",
            "status": "decline",
            "date": "2025-01-28T10:45:41+0000",
            "created_date": "2025-01-28T10:45:18+0000",
            "request_id": "080bc706bb3fa2f3ec4509055e-00006297"
        },
        "signature": "WpWZ+gvMPe9ldONXZEUZpRisl3m+udOyy21XZBYftVTWg=="
    }

Useful links

The following articles can be useful when implementing purchases via Gate:

Analysis of payments results

To analyse information about payments made with the Purchases via Mbank bank accounts method and other methods, you can use:

  • Dashboard interface toolkit with various lists and analytic panels.
  • Reports in CSV file format, available via the Reports section (one-time and periodically).
  • Data in JSON format, sent by program requests to a specified URL available by using the Data API interface.

If you have any questions, refer to the documentation (Dashboard and Using Data API) and Flashpay technical support.