Mobile Commerce

Overview

Mobile Commerce is a payment method which allows processing payments by using mobile billing. Purchases can be processed by using Payment Page and Gate, payouts by using Gate and Dashboard (Old Dashboard).

General information

Payment method type Mobile commerce
Countries and regions

BI, CI, CM, GH, KE, KZ, RU, RW, UG, ZM

Payment currencies

BIF, GHS, KES, KZT, RUB, RWF, UGX, USD, XAF, ZMW

Currency conversion
Purchases +
Payouts + (supported by particular mobile operators)
Stored credentials payments
Full refunds
Partial refunds
Chargebacks
Notes In order to confirm payment, submission of additional payment information may be required
Onboarding and access fee Refer to your ECommPay key account manager

Interaction diagram

Payment processing by using the Mobile Commerce payment method requires the use of merchant's web service, one of ECommPay interfaces, and the ECommPay payment platform, as well as the service of the mobile network operator.



Operations support

  Interfaces Times**
Payment Page CMS Plug-ins Gate Dashboard (Old Dashboard) basic threshold
Purchases + + * *
Payouts + + * *

* For more information refer to your ECommPay key account manager.

** The basic and threshold times are defined as follows:

  • The basic 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 initiator. The basic 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 customer is required). Use the basic time to estimate when to react to the absence of payment result notifications or when to check payment status.
  • The threshold time is the maximum possible time from the moment a payment is initiated in the payment platform to the moment the information about the payment result is sent to the initiator. A payment is automatically declined, if its waiting time exceeds the threshold time. For individual setting of the threshold time limit, contact ECommPay technical support.

Processing scenarios

In course of purchase processing the customer receives necessary information from mobile network operator and makes the required steps to confirm withdrawal of funds from the customer's mobile phone account.To perform a payout, the customer only needs to make a query, and the funds are credited to the customer's mobile phone account.

The following sections provide detailed information about what you need to do to perform payments, including test payments, and how you can analyse the information on payments.

Supported mobile operators

Payments involving the Mobile Commerce method are carried out through services of mobile network operators that support the use of this method.

Table 1. Supported mobile operators and their payment amount limits
Mobile operator Identifier Countries Currencies Amounts
minimum maximum
Beeline BEELINE RU, KZ RUB, KZT
  • Purchases in Russia: 10.00 RUB
  • Payouts in Russia: 1.00 RUB
  • Purchases in Kazakhstan: 5.00 KZT
  • Purchases in Russia: 15,000.00 RUB
  • Payouts in Russia: 15,000.00 RUB
  • Purchases in Kazakhstan: 60,000.00 KZT or 200,000.00 KZT *
MTS MTS RU RUB Purchases and payouts: 1.00 RUB
  • Purchases: 14,999.00 RUB
  • Payouts: 15,000.00 RUB
Tele2 TELE2 RU, KZ RUB, KZT
  • Purchases and payouts in Russia: 1.00 RUB
  • Purchases in Kazakhstan: 5.00 KZT
  • Purchases in Russia: 15,000.00 RUB
  • Payouts in Russia: 15,000.00 RUB
  • Purchases in Kazakhstan: 60,000.00 KZT or 200,000.00 KZT *
Megafon MEGAFON RU RUB Purchases and payouts: 1.00 RUB
  • Purchases: 15,000.00 RUB
  • Payouts: 15,000.00 RUB
Activ ACTIV KZ KZT Purchases: 200.00 KZT Purchases: 148,850.00 KZT
Altel ALTEL KZ KZT Purchases: 5.00 KZT Purchases: 60,000.00 KZT or 200,000.00 KZT *
Aitrtel AIRTEL GH, RW, UG GHS, RWF, UGX * *
Econet ECONET BI BIF, USD * *
Kcell KCELL KZ KZT Purchases: 200.00 KZT Purchases: 148,850.00 KZT
MTN MTN CI, CM, GH, RW, UG, ZM GHS, RWF, UGX, USD, ZMW * *
M-Pesa MPESA KE KES * *
Orange ORANGE CM USD, XAF * *
Tigo TIGO GH GHS * *
Vodafone VODAFONE GH GHS * *

* For information about amount limits, refer to your ECommPay key account manager.

The list of supported mobile operators and countries can be obtained through sending a request to one of the endpoints of the group /v2/info/mobile/{operation_type}/list by using POST (HTTP) method through Gate API:
  • /v2/info/mobile/sale/list—for obtaining the list of mobile operators and countries that support purchases
  • /v2/info/mobile/payout/list—for obtaining the list of mobile operators and countries that support payouts

The request must include project ID and signature, as follows:

Figure: Example of data in the request for obtaining the list of supported operators and countries

{
  "general": {
    "project_id": 200,
    "signature": "K6jllym+PtObocZtr345st=="
  }
}

Purchases by using Payment Page

General information

To process a purchase through Payment Page by using the Mobile Commerce method, the merchant web service should send a request with all the required parameters and signature to the ECommPay URL and receive a callback with information about the payment result from the payment platform. The Mobile Commerce method can also be set as preselected payment method when Payment Page opens (more). The full sequence of the purchase process is provided below.



Figure: Purchase processing by using Payment Page: Step-by-step description

  1. Customer initiates a purchase in the merchant's web service.
  2. The web service sends the request for opening Payment Page to the specified ECommPay URL.
  3. The request for opening Payment Page is redirected to the payment platform.
  4. The payment platform performs the initial request processing that involves validation of the required parameters and signature.
  5. In the ECommPay payment platform Payment Page is generated based on the project settings and parameters specified in the request.
  6. Payment Page is displayed to the customer.
  7. The customer selects the Mobile Commerce method.
  8. The form for entering mobile number is displayed to the customer.
  9. The customer selects mobile operator and enters number of the mobile phone subscriber whose account will be used for purchase.
  10. The request for processing the payment is sent from Payment Page to the payment platform.
  11. The payment platform processes the request and sends it to the service of mobile network operator.
  12. The request is processed on the side of the service of mobile network operator.
  13. An SMS with confirmation code is sent to the customer, or payment instruction is displayed to the customer.
  14. The customer completes all the payment steps required.
  15. The payment is processed on the side of the service of mobile network operator.
  16. The result is displayed to the customer on the side of the service of mobile network operator.
  17. The customer is redirected to Payment Page.
  18. The service of mobile network operator sends a notification about the result to the payment platform.
  19. The payment platform sends a callback with the payment result to the web service.
  20. The payment platform sends notification about the result to Payment Page.
  21. Information about the payment result is displayed to the customer on Payment Page.

By default, when the Mobile Commerce is used, the customer selects the method first and then the mobile network operator. However, the ECommPay payment platform also supports the option of preselecting mobile network operator or country. If this option is enabled, step 7 of the purchase processing flow is omitted and on step 9 the customer only needs to enter the mobile phone number.

In course of purchase request processing, to confirm the payment, one of the following options may be used depending on the specifics of the service of mobile network operator:

  • In the payment form the customer specifies the purchase confirmation code received in an SMS.
  • The customer makes the required steps in accordance with the displayed payment instructions.

To provide for these options, submission of additional payment information is used (more).

The following sections discuss in more details the request format and the Payment Page parameters to use in the Mobile Commerce payment method and provide the information on the format of callbacks with payment results. For the general information on how to use the API, see Payment Page API Description.

Request format

There are several things you need to consider when using the Mobile Commerce method:

  1. You must provide values for the basic minimum of parameters. Listed below are the parameters that are mandatory for any payment method:
    • project_id—the project ID obtained from ECommPay
    • payment_id—payment ID unique within the project
    • customer_id—customer ID unique within the project
    • payment_currency—payment currency code in ISO-4217 alpha-3 format
    • payment_amount—payment amount in minor units
  2. The currency of purchase can be any from the General information table.
  3. If you need the payment form to open with the Mobile Commerce method as preselected payment method, set the force_payment_method parameter to mobile. To set a preselected mobile network operator or country, you need to additionally specify in the request the payment_methods_options object which contains the following parameters:
    • enable_mobile_service—an indicator of preselection of mobile network operator and country. You should specify the 1 value for this parameter if the mobile network operator or country is selected in the web service.
    • selected_operator—identifier of the selected mobile network operator in accordance with the Supported mobile operators and their payment amount limits table.
    • selected_country—country code according to ISO 3166-1 alpha-2.
  4. If required, you can also add any other additional parameters Payment Page supports. For information about all parameters available for the Mobile Commerce method, see Payment Page invocation parameters.
  5. After you specify all the parameters you need, you must create the signature for the request. For instructions on how to sign a payment request, see Signature generation and verification.

Thus, a correct request for opening the payment form involving the Mobile Commerce method must include project, customer and payment IDs, currency code and amount of the payment, and signature, and may also include other parameters:

Figure: Example of data in the request for opening Payment Page with method selection by customer

{
    project_id: 1380,
    payment_id: '936', 
    customer_id: 'customer1',
    payment_currency: 'KZT',
    payment_amount: 25000,
    signature: "jhfdudu4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
}

Figure: Example of data in the request for opening Payment Page with preselected payment method and mobile network operator

{
    project_id: 1380,
    payment_id: '736', 
    customer_id: 'customer1',
    payment_currency: 'KZT',
    payment_amount: 25000,
    force_payment_method: 'mobile',
    payment_methods_options: {
        "enable_mobile_service": 1,
        "selected_operator": "TELE2"
    },
    signature: "kanfgwi8dtdxtEEyvk1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOcZzUCwsbbk8hkIQg=="
}

Figure: Example of data in the request for opening Payment Page with preselected payment method and country

{
    project_id: 1380,
    payment_id: '736', 
    customer_id: 'customer1',
    payment_currency: 'KZT',
    payment_amount: 25000,
    force_payment_method: 'mobile',
    payment_methods_options: {
        "enable_mobile_service": 1,
        "selected_country": "KZ"
    },
    signature: "awegiyqedxtEEyvk1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
}

Callback format

The Mobile Commerce method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with an information about successful 800.00 RUB purchase from account 79821234567 made in the 382 project.

Figure: Example of a successful purchase callback

 {
        "customer": {
            "id": "sc-997741"
        },
        "payment": {
            "date": "2019-10-18T07:30:50+0000",
            "id": "e16d0d998485698c652f96f6b2ff8826",
            "method": "mobile",
            "status": "success",
            "sum": {
                "amount": 80000,
                "currency": "RUB"
            },
            "type": "purchase",
            "account": {
                "number": "79821234567"
            },
            "description": ""
        },
        "project_id": 382,
        "operation": {
            "id": 7375000008886,
            "type": "sale",
            "status": "success",
            "date": "2019-10-18T07:30:50+0000",
            "created_date": "2019-10-18T07:29:08+0000",
            "request_id": "83a47d9a5f5677b55fe534d9a9c0335a18-00007376",
            "sum_initial": {
                "amount": 80000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 80000,
                "currency": "RUB"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1078,
                "payment_id": "118665991",
                "auth_code": ""
            }
        },
        "account": {
            "type": "MTS"
        },
        "signature": "gf5CBRhCgltRUoXMUJ38qX/T1jhDE1kOvJFfD/iKk7x+hWE01bmFeT
                                         K1fowqyrIQoqy76z1x5B9jwOkuJcrVEA=="
    }
}

The following is the example of a callback for a purchase declined due to insufficient funds on customer account.

Figure: Example of a declined purchase callback

{
        "project_id": 981,
        "payment": {
            "id": "93688696",
            "type": "purchase",
            "status": "decline",
            "date": "2019-10-18T07:32:26+0000",
            "method": "mobile",
            "sum": {
                "amount": 30000,
                "currency": "RUB"
            },
            "description": ""
        },
        "account": {
            "number": "79051234567",
            "type": "mBEELINE"
        },
        "customer": {
            "id": "1028232202"
        },
        "operation": {
            "id": 29839000009286,
            "type": "sale",
            "status": "decline",
            "date": "2019-10-18T07:32:26+0000",
            "created_date": "2019-10-18T07:08:26+0000",
            "request_id": "8ff0457e32ad81b524a807d7a307ffa9ae8f03aadb0b-00029840",
            "sum_initial": {
                "amount": 30000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 30000,
                "currency": "RUB"
            },
            "code": "20105",
            "message": "Insufficient funds on customer account",
            "provider": {
                "id": 1078,
                "payment_id": "118662791",
                "auth_code": ""
            }
        },
        "signature": "ZdfYgsg02Mhd1c/43dOK8v2s3rnFr7I+2uqIZ=="
    }
}

Related topics

The following topics might be useful when implementing payments by using Payment Page:

Purchases by using Gate

General information

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

  1. Send a request with all the required parameters and signature to the ECommPay URL.
  2. If necessary, receive intermediate callback with additional information from the ECommPay payment platform and make the required steps.
  3. Get the callback with information about the payment result from the payment platform.

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

Figure: Purchase processing by using Gate: Step-by-step description

  1. A customer initiates a purchase on the side of merchant's web service.
  2. The web service sends the request for processing the purchase by using Gate to the specified ECommPay URL.
  3. The payment platform receives the request for purchase processing from Gate.
  4. The payment platform performs the initial request processing that includes validation of the required parameters and signature.
  5. The payment platform sends the response with confirmation of receipt of the request and information about its correctness to the web service. For more information, see Response format.
  6. The payment platform performs the internal payment request processing and redirects the request to the service of mobile network operator.
  7. The request is processed on the side of the service of mobile network operator.
  8. An SMS with confirmation code is sent to the customer. This step is not required for some of the mobile network operators. In some cases the customer needs to specify the code on the side of the web service, and so web service needs to send the request with the code to the payment platform.
  9. The customer completes all the payment steps required. In some cases it may be required to display the payment instructions to the customer on the web service side. The data for displaying the payment instructions is sent in a callback from the payment platform.
  10. The payment is processed on the side of the service of mobile network operator.
  11. The information about the result is displayed to the customer.
  12. The service of mobile network operator sends the payment result notification to the payment platform.
  13. The payment platform sends a callback to the web service.
  14. The customer receives information about the payment result on the side of the web service.

The following sections discuss in more details the request format and the Gate parameters to use in the Mobile Commerce 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 Mobile Commerce method:
  1. You send purchase requests by sending the request to /v2/payment/mobile/sale by using the POST (HTTP) method.
  2. The following objects and parameters must be specified in any request:
    • Object general—general purchase information:
      • project_id—the project ID obtained from ECommPay
      • 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
    • Object customer—customer information:
      • id—customer ID unique within the project
      • ip_address—customer IP address
    • Object account—customer account information:
      • number—customer mobile phone number for debiting; the number must be specified with a country code and without punctuation or special characters (for example, 79031234567)
      • service_provider*—identifier of the mobile network operator
    • Object payment—purchase information:
      • amount—purchase amount
      • currency—payout currency in the ISO-4217 alpha-3 format
      • description*—payment description
    Note: * These parameters are not required for all mobile network operators. It is recommended to use submission of additional payment information.
  3. The currency of purchase can be any currency from the General information table.
  4. If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request for purchase processing by using the Mobile Commerce method must include project and payment IDs, signature, customer IP address, ID and mobile phone number, currency and amount of the purchase, and may also include other parameters:

Figure: Example of data in a purchase request

{
  "general": {
    "project_id": 382,
    "payment_id": "e16d0d998485698c652f96f6b2ff8826",
    "signature": "3zjYFqRhDsaTLF7FVv4+2uWs1KaaWIHaNUPcN4sF6x4Um+K4SAyamNnFVg=="
  },
  "customer": {
    "ip_address": "127.0.0.1",
    "id": "customer123"
  },
  "account": {
    "number": "79821234567",
    "service_provider": "TELE2"
  },
  "payment": {
    "amount": 80000,
    "currency": "RUB"
  }
}

Formats of callbacks and requests for submission of additional payment information

When the customer needs to specify the confirmation code received from the mobile network operator in order to confirm payment, the payment platform sends a callback to the web service about the need to submit additional payment information. In this case, the merchant web service needs to receive payment confirmation code from the customer (in the payment interface of the web service), send a POST request with the payment confirmation code to the /v2/payment/clarification endpoint and receive a 200 OK response from the platform.

The callback contains the clarification_fields array which contains the approval_codeparameter—payment confirmation code which the customer receives in an SMS and specifies on the web service side. The lifespan of the confirmation code is 90 seconds (starting when the code is created on the side of the mobile network operator). During this time the information about the code specified by the customer should be received by the mobile network operator.

Figure: Example of data in callback informing about the need to submit additional payment information

{
  "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 POST (HTTP) method. The request must contain the following objects and parameters:

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

Thus, a correct request must include project and payment IDs, signature and payment confirmation code:

Figure: Example of data in the request for payment processing with regard to additional payment information

{
  "general": {
    "project_id": 11,
    "payment_id": "EPr-bf14",
    "signature": "v7KNMpfogAthg1ZZ5D/aZAeb0VMdeR+CqghwSm...=="
  },
  "additional_data": {
    "approval_code": "25845775XZnv1vDN"
  }
}

It is recommended to send request with the confirmation code within 80 seconds after receiving the callback with the clarification_fields array so payment processing is confirmed on the payment provider side in a timely manner. As this request is sent, payment processing may continue as follows:

  • If the confirmation code is sent on time and is correct, the payment processing continues on the side of the payment platform and payment provider service, and after that a final callback is sent to the web service.
  • If the confirmation code is sent on time but is incorrect, a callback with the clarification_fields is resent from the payment platform to the web service. In this case you should provide the customer with an opportunity to specify the correct confirmation code once more and you should send request with this confirmation code to the payment platform (also within 80 seconds).
  • If the confirmation code is sent after 80 seconds, the following options are possible:
    • If the confirmation code is sent on time and is correct, payment processing continues on the side of the payment platform and mobile network operator, and after that a callback with information about the result is sent to the web service.
    • If the confirmation code is incorrect or expired, a callback with the clarification_fields is resent from the payment platform to the web service. In this case it is recommended to send a request for sending another confirmation code to the customer to the payment platform, then receive the new code from the customer and send request for payment processing with regard to this code.

The request for sending a new confirmation code to the customer is sent by using POST (HTTP) method to the /v2/customer/action/resend endpoint which belongs to the /v2/customer/action/{action_name} group. The request must contain the following objects and parameters:

  • general—object that contains general request identification information:
    • project_id—the ID of the project to which the payment is related
    • payment_id—the payment ID unique within the project
    • signature—signature generated after all of the required parameters are specified (for more information, see Signature generation and verification)
  • customer—object that contains customer information:
    • ip_address—customer IP address

Thus, a correct request must include project and payment IDs, signature and customer IP address:

Figure: Example of data in the request for sending another confirmation code to the customer

{
  "general": {
    "project_id": 382,
    "payment_id": "e16d0d998485698c652f96f6b2ff8826",
    "signature": "3zjYFqRhDsaTLF7FVv4yu+Ziereqwr4343x/wG...FVg=="
  },
  "customer": {
    "ip_address": "85.140.0.68"
  }
}

In terms of one payment additional codes can be issued up to three times. Each of the sent codes is valid within 90 seconds starting when the code is created on the side of payment provider.

Warning: Callbacks with information about payment and operation statuses may be sent from the payment platform to the web service. Due to specifics of the workflow of mobile network operator service, payment and operation statuses in these notifications may be incorrect, hence it is recommended to disregard it.

Formats of data for displaying payment instructions

In some cases (depending on the payment processing provider) instead of specifying the confirmation code the customer may be required to follow the payment instructions to complete the payment. To display the payment instructions to the customer, you must receive and process a callback from the payment platform containing the payment data in the in the display_data which includes the following objects:

  • type—object type (the value is always add_info)
  • title—sequence number of the instructions step, which must be followed by the customer
  • data—contents of the instruction step specified in the title parameter

Figure: Example of data in callback containing payment instruction

"display_data": [
        {
            "type": "add_info",
            "title": "step 1",
            "data": "Ensure that you have sufficient balance on your mobile money account"
        },
        {
            "type": "add_info",
            "title": "step 2",
            "data": "Approve the payment request sent to your phone"
        }
    ]

Callback format

The Mobile Commerce method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with an information about successful 800.00 RUB purchase from account 79821234567 made in the 382 project.

Figure: Example of a successful purchase callback

 {
        "customer": {
            "id": "sc-997741"
        },
        "payment": {
            "date": "2019-10-18T07:30:50+0000",
            "id": "e16d0d998485698c652f96f6b2ff8826",
            "method": "mobile",
            "status": "success",
            "sum": {
                "amount": 80000,
                "currency": "RUB"
            },
            "type": "purchase",
            "account": {
                "number": "79821234567"
            },
            "description": ""
        },
        "project_id": 382,
        "operation": {
            "id": 7375000008886,
            "type": "sale",
            "status": "success",
            "date": "2019-10-18T07:30:50+0000",
            "created_date": "2019-10-18T07:29:08+0000",
            "request_id": "83a47d9a5f5677b55fe534d9a9c0335a18-00007376",
            "sum_initial": {
                "amount": 80000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 80000,
                "currency": "RUB"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1078,
                "payment_id": "118665991",
                "auth_code": ""
            }
        },
        "account": {
            "type": "MTS"
        },
        "signature": "gf5CBRhCgltRUoXMUJ38TK1fowqyrIQoqy76z1x5B9jwOkuJcrVEA=="
    }
}

The following is the example of a callback for a purchase declined due to insufficient funds on customer account.

Figure: Example of a declined purchase callback

{
        "project_id": 981,
        "payment": {
            "id": "93688696",
            "type": "purchase",
            "status": "decline",
            "date": "2019-10-18T07:32:26+0000",
            "method": "mobile",
            "sum": {
                "amount": 30000,
                "currency": "RUB"
            },
            "description": ""
        },
        "account": {
            "number": "79051234567",
            "type": "BEELINE"
        },
        "customer": {
            "id": "1028232202"
        },
        "operation": {
            "id": 29839000009286,
            "type": "sale",
            "status": "decline",
            "date": "2019-10-18T07:32:26+0000",
            "created_date": "2019-10-18T07:08:26+0000",
            "request_id": "8ff0457e32ad81b524a807d7a307ffa9ae8f03aadb0b-00029840",
            "sum_initial": {
                "amount": 30000,
                "currency": "RUB"
            },
            "sum_converted": {
                "amount": 30000,
                "currency": "RUB"
            },
            "code": "20105",
            "message": "Insufficient funds on customer account",
            "provider": {
                "id": 1078,
                "payment_id": "118662791",
                "auth_code": ""
            }
        },
        "signature": "ZdfYgsg02Mhd1c/OK8v2s3rnFr7I+2uqIZCQ5Kc9Pr/qXZcGUyIvyu3
                                           8yF0F7ZudmdYY3Thzh6Fpj9/kKHTWKQ=="
    }
}

Related topics

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

Payouts by using Gate

General information

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

Figure: Payout by using Gate

  1. A customer orders a payout through the Mobile Commerce system.
  2. Merchant's web service sends the request for the payout processing by using Gate to the appropriate ECommPay URL.
  3. Gate redirects the request to the ECommPay payment platform.
  4. The payment platform performs all the necessary checks 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 format.
  6. The payment platform redirects the payout request to the Mobile Commerce service.
  7. The payout is processed on the Mobile Commerce side.
  8. Mobile Commerce 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 notification about 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 Mobile Commerce 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 Mobile Commerce method:
  1. You send payout requests by sending the /v2/payment/mobile/payout request by using HTTP method POST.
  2. The following objects and parameters must be specified in any request:
    • Object general—general payout information:
      • project_id—project identifier
      • payment_id—unique payout identifier
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
    • Object customer—customer information:
      • id—identifier
      • ip_address—customer IP address
      • first_name*—first name
      • last_name*—last name
    • Object account—customer account information:
      • number—customer mobile number for payout; the number must be specified using a country code and without punctuation or special characters, for example 79031234567, you can read more about the format in the FAQ section
      • service_provider*—identifier of the mobile operator
    • Object payment—payout information:
      • amount—payout amount
      • currency—payout currency in the ISO-4217 alpha-3 format.
    Note: * These parameters are not required for all mobile operators. Refer to your ECommPay key account manager for more information.
  3. The currency of payout can be any from the General information table.
  4. If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request in the Mobile Commerce method must include project and payment IDs, signature, information about the customer and mobile phone number, currency and amount of the payout, as shown in the following example:

Figure: Example of a payout request

{
    "general": {
        "project_id": 35,
        "payment_id": "payout_65",
        "signature": "akchavu5w7v8vwg467Zie3x/wG8JuRey87Q4Oyb3FzF+2uWs1KaaWIHa
                                                 NUPcN4sF6x4Um+K4SAyamNnFVg=="
    },
    "customer": {
        "id": "user45",
        "ip_address": "1.2.3.4"
    },
    "account": {
        "number": "79123456789",
        "service_provider": "MTN"
    },
    "payment": {
        "amount": 10000,
        "currency": "KZT"
    }
}

Callback format

The Mobile Commerce method uses the standard format for callbacks to deliver payout results. For more information, see Callbacks.

The following is the example of a callback with an information about successful 724.00 KZT payout to account 79897439125 made to the 1000000000946308 customer in the 25 project.

Figure: Example of a successful payout callback

{
        "sum_request": {
            "amount": 72400,
            "currency": "KZT"
        },
        "request_id": "f7cf554411e67d2598159361644bc02ba08f4d64-00063844",
        "transaction": {
            "id": 63843000000321,
            "date": "2019-10-31T07:00:08+0000",
            "type": "payout"
        },
        "payment": {
            "id": "13614419800",
            "method": "mobile",
            "date": "2019-10-31T07:00:08+0000",
            "result_code": "0",
            "result_message": "Success",
            "status": "success",
            "is_new_attempts_available": false,
            "attempts_timeout": 0,
            "cascading_with_redirect": false,
            "provider_id": 14
        },
        "sum_real": {
            "amount": 72400,
            "currency": "KZT"
        },
        "customer": {
            "id": "1000000000946308"
        },
        "account": {
            "number": "79897439125"
        },
        "rrn": "",
        "general": {
            "project_id": 25,
            "payment_id": "13614419800",
            "signature": "efy09xOugbWMreW0T6I3VCz7rlRCqHTA2SiIm4X2H0fl804sB3VDZPEdK7r0
                                                          O/kR349nj7KcokTGpi23kiJlQ=="
        },
        "description": "test payout",
        "operations": [
            {
                "id": 63843000000371,
                "type": "payout",
                "status": "success",
                "date": "2019-10-31T07:00:08+0000",
                "processing_time": null,
                "request_id": "f7cf554411e67d2598159361644bc02ba08f4d64-00063844",
                "sum": {
                    "amount": 72400,
                    "currency": "KZT"
                },
                "code": "0",
                "message": "Success"
            }
        ]
    }

The following is the example of a callback for a payout declined due to customer account being no longer available.

Figure: Example of a declined payout callback

{
        "sum_request": {
            "amount": 650000,
            "currency": "KZT"
        },
        "request_id": "647c8ea772328e5df288344b5e6c57b207fda92-00013521",
        "transaction": {
            "id": 13520000009331,
            "date": "2019-10-31T08:44:02+0000",
            "type": "payout"
        },
        "payment": {
            "id": "13612847900",
            "method": "mobile",
            "date": "2019-10-31T08:44:02+0000",
            "result_code": "20106",
            "result_message": "Customer account is no longer available",
            "status": "decline",
            "is_new_attempts_available": false,
            "attempts_timeout": 0,
            "cascading_with_redirect": false,
            "provider_id": 14
        },
        "sum_real": {
            "amount": 650000,
            "currency": "KZT"
        },
        "customer": {
            "id": "1000000000930682"
        },
        "account": {
            "number": "79534158916"
        },
        "rrn": "",
        "general": {
            "project_id": 131,
            "payment_id": "13612847900",
            "signature": "V5bloYlpjQrL9PUBUJug9i8jb30vdC411W/le6AFZXLUuX5HQH1zYxWe
                                                 4n2hAj0CSM1Ew/HuQ8ivuLOFwEpJ2A=="
        },
        "description": "test payout",
        "operations": [
            {
                "id": 13520000010671,
                "type": "payout",
                "status": "decline",
                "date": "2019-10-31T08:44:02+0000",
                "processing_time": null,
                "request_id": "647c8ea772328e51c289ea2a5387157b207fda92-00013521",
                "sum": {
                    "amount": 650000,
                    "currency": "KZT"
                },
                "code": "20106",
                "message": "Customer account is no longer available"
            }
        ]
    }

Related topics

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

Payouts by using Dashboard (Old Dashboard)

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

Information about performed payouts is displayed in the Payments section of Dashboard (Old Dashboard).

More detailed information on the payout processing by using Dashboard (Old Dashboard) is provided in the Performing payouts section.

Testing

General information

For the Mobile Commerce method the testing of purchases by using Payment Page and Gate, payouts by using Gate is available. Testing can be performed within a test project, to enable and disable the testing availability, contact ECommPay technical support.

When performing a test payment, take into account that you must specify the identifier of the test project in the requests, the currency can be only RUB, and the interface of the payment form may differ from the one used in the production environment.

Test payments statuses

When testing purchases, the final payment statuses are determined by the amounts specified in requests:

  • decline status with 40000 or 40400 amount
  • success status with any other amount

When testing payouts, the final payment statuses are determined by the amounts specified in requests:

  • decline status with 40000 or 40400 amount
  • success status with any other amount

Purchases by using Payment Page

To perform a test purchase by using Payment Page, do the following:

  1. Send a correct test request for Payment Page opening to the payment platform.
  2. If the mobile method was not specified in the request—select the method.
  3. Specify a random phone number with the correct country code in the data entry field (e.g. 79031234567) and click the Pay button.
  4. Make sure that the countdown timer appears and that the information on the result of the payment is displayed in 20 seconds.
  5. Accept a callback with information about the payment result.

The full information about purchase process by using Mobile Commerce through Payment Page is provided in the section Purchases by using Payment Page of this article.

Purchases by using Gate

To perform a test payout by using Gate, send a correct test request to the payment platform and accept a callback with information about the payment result. The full information about purchase process by using Mobile Commerce through Gate is provided in the section Purchases by using Gate.

Payouts by using Gate

To perform a test payout by using Gate, send a correct test request to the payment platform and accept a callback with information about the payment result. The full information about payout process by using Mobile Commerce through Gate is provided in the section Payouts by using Gate.

Analysis of payments results

As with other payment methods ECommPay offers, when using the Mobile Commerce method, you have several options to analyse the information about payments and operations performed by using the method—alone or in conjunction with other methods.

You can load and analyse all the necessary information in Dashboard (Old Dashboard), 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 (Old 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 ECommPay technical support.