Mobile Commerce

Overview

Mobile Commerce is a payment method for payments based on the customer phone number. You can perform purchases through this method by using Payment Page and Gate, payouts by using Gate and Dashboard (Old Dashboard).

General information

Payment method type Mobile commerce
Countries and regions

GH, KE, KZ, RU

For more information about restrictions of supported mobile operators Supported mobile operators and their payment limits

Payment currencies

GHS, KES, KZT, RUB

For more information about restrictions of supported mobile operators Supported mobile operators and their payment limits

Currency conversion
Purchases +
Payouts + (are not supported by all mobile operators)
Stored credentials payments
Full refunds
Partial refunds
Chargebacks
Notes
  • The funds are debited from the customer's mobile phone account. The funds are credited to the customer's mobile phone account
  • We recommend to use additional payment information submission for performing purchases by using Gate
Onboarding and access fee Refer to your ECommPay key account manager

Interaction diagram

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

Operations support

  Interfaces Times**
Payment Page CMS Plugins 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 between the moment a payment is initiated in the payment platform to the moment the initiator receives the callback with the payment result. 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

While performing purchases the funds are debited from the customer's mobile phone account. While performing payouts the funds are credited to the customer's mobile phone account.

Figure: Purchase by using Payment Page



Figure: Purchase by using Gate



Figure: Payout by using Gate



Supported mobile operators

Payments through the Mobile Commerce method are carried out through mobile operators that support the work with this method.

For full information on supported mobile operators and countries send the /v2/info/mobile/{operation_type}/list POST HTTP request by using Gate API:
  • /v2/info/mobile/sale/list—for the list of mobile operators and countries that support purchases
  • /v2/info/mobile/payout/list—for the list of mobile operators and countries that support payouts
Table 1. Supported mobile operators and their payment 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
Altel ALTEL KZ KZT Purchases: 5,00 KZT Purchases: 60,000.00 KZT or 200,000.00 KZT *
MTN** MTN GH GHS * *
M-Pesa** MPESA KE KES * *
Tigo** TIGO GH GHS * *
Vodafone** VODAFONE GH GHS * *

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

** When initiating payouts by using Gate through the MTN, M-Pesa, Tigo and Vodafone mobile operators, numerical identifiers must be specified in payout requests. The values of the identifiers are presented in the table Identifiers of mobile operators.

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

Purchases by using Payment Page

General information

When using the Mobile Commerce method, when processing a purchase by using Payment Page, the merchant web service should send a request with all the required parameters and signature to the ECommPay URL and get the callback with the payment result from the payment platform. When opening Payment Page, you can have Payment Page opened with the Mobile Commerce method selected. For more information about preselecting payment methods, see in Preselecting payment method. The full sequence and particularities of the purchase process are provided below.

Figure: Purchase sequence in the Payment Page method:

  1. A customer initiates a purchase on the merchant's web service.
  2. The web service sends the request for Payment Page opening to the specified ECommPay URL.
  3. The request for opening 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. Requested Payment Page is generated into the ECommPay payment platform as specified in the project settings and the request parameters.
  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 mobile number for purchase.
  10. The payment platform receives the purchase request for payment processing from Payment Page.
  11. The payment platform performs the internal purchase request processing and sends it to the Mobile Commerce service.
  12. The purchase request is processed on the Mobile Commerce service side.
  13. The customer receives SMS with confirmation code. But for some mobile operators the payment instruction is displayed to the customer.
  14. The customer completes all the payment steps required.
  15. The payment is processed on the Mobile Commerce side.
  16. The result is displayed to the customer on the Mobile Commerce website.
  17. The customer is redirected to Payment Page.
  18. The Mobile Commerce service sends the result notification to the payment platform.
  19. The payment platform sends a callback with the payment result to the web service.
  20. The payment platform sends the result to Payment Page.
  21. A page with the payment result information is displayed to the customer on Payment Page.

The sections that follow 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
    • payment_currency—payment currency in ISO-4217 alpha-3 format
    • payment_amount—payment amount in minor units
    • customer_id—customer ID unique within the project
  2. The currency of purchase can be any from the General information table.
  3. If you need to have payment form displayed with the Mobile Commerce method selected, set the force_payment_method parameter to mobile.
  4. If the customer_phone parameter is used in the request, the phone number in the value of the parameter must be specified using a country code and without the + sign, for example 79031234567.
  5. If required, you can also add any other additional parameters Payment Page supports.
  6. 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 payment request in the Mobile Commerce method must include project and payment IDs, the amount and currency of payment and signature, as shown in the following example:

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

For information about all parameters available in the Mobile Commerce method , see Payment Page invocation parameters.

Additional capabilities

By default all mobile operators are grouped in one button on Payment Page, so the selection of a mobile operator is carried out in two steps. Firstly, customer selects the payment method, and then the mobile operator.

For the Mobile Commerce method it is possible to use additional service (mobile service) to set the pre-selection of payment method on Payment Page. To use that service contact the ECommPaytechnical support, so they could change project settings.

After that you need to pass payment method code in the force_payment_method parameter and additional parameters in the payment_methods_options object. The payment_methods_options object may contain the following parameters:
  • enable_mobile_service—sign of using the mobile service, always pass 1 in the parameter
  • selected_operator—mobile operator identifier for pre-selection. The list of identifiers see in the Supported mobile operators and their payment limits table
  • selected_country—country code according to ISO 3166-1 alpha-2

Figure: Example of the request for Payment Page opening with pre-selected mobile operator

EPayWidget.run(
    { payment_id: 'test736', 
      payment_amount: 25000, 
      payment_currency: 'KZT', 
      project_id: 1380, 
      force_payment_method: 'mobile',
      payment_methods_options = {"enable_mobile_service":1, "selected_operator": "TELE2"},
      signature: "kanfgwi8dtdxtEEyvk1Y4HASCQ9vySO\/RLCvhtT4DqtVUkDJrOcZzUCwsbbk8hkIQg=="
    }
)

Figure: Example of the request for Payment Page opening with pre-selected group of mobile operators from the same country

EPayWidget.run(
    { payment_id: 'test936', 
      payment_amount: 25000, 
      payment_currency: 'KZT', 
      project_id: 1380, 
      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 KZT purchase from account 79821234567 made by the sc-997741 customer 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": "KZT"
            },
            "type": "purchase",
            "account": {
                "number": "79821234567"
            },
            "description": "test payment"
        },
        "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": "KZT"
            },
            "sum_converted": {
                "amount": 80000,
                "currency": "KZT"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1078,
                "payment_id": "118665991",
                "auth_code": ""
            }
        },
        "account": {
            "type": "mTELE2"
        },
        "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": "invoice_93688696",
            "type": "purchase",
            "status": "decline",
            "date": "2019-10-18T07:32:26+0000",
            "method": "mobile",
            "sum": {
                "amount": 30000,
                "currency": "KZT"
            },
            "description": "test payment"
        },
        "account": {
            "number": "79051234567",
            "type": "mTELE2"
        },
        "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": "KZT"
            },
            "sum_converted": {
                "amount": 30000,
                "currency": "KZT"
            },
            "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 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. 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 by using Gate

  1. A customer initiates a purchase through Mobile Commerce on the merchant's web service side.
  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 processing the purchase 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 request receipt confirmation and correctness check result 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 Mobile Commerce service.
  7. The request is processed on the Mobile Commerce side.
  8. The customer receives SMS with confirmation code. That step is not necessary for some of the mobile operators. In some cases the customer needs to specify the code on the web service side and the web service needs to send the request with the code to the payment platform.
  9. The customer completes all the payment steps required.
  10. The payment is processed on the Mobile Commerce side.
  11. The result is displayed to the customer.
  12. The Mobile Commerce service sends the payment result notification to the payment platform.
  13. The payment platform sends a callback to the web service.
  14. The customer receives the payment result on 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 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 /v2/payment/mobile/sale request by using HTTP method POST.
  2. The following objects and parameters must be specified in any request:
    • Object general—general purchase information:
      • project_id—project identifier
      • payment_id—unique purchase 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—unique ID within the merchant project
      • ip_address—customer IP address
    • Object account—customer account information:
      • number—customer phone number for debiting; the number must be specified using a country code and without the + sign, for example 79031234567
      • service_provider*—identifier of the mobile operator (see Supported mobile operators and their payment limits)
    • 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 operators. We recommend to use additional payment information submission
  3. The currency of purchase can be any from the General information table.
  4. If required, you can also add any other additional parameters Gate supports.
  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 payment request in the Mobile Commerce method must include project and payment IDs, signature, customer IP address and mobile number, currency and amount of the purchase, as shown in the following example:

Figure: Example of a purchase request

{
  "general": {
    "project_id": 382,
    "payment_id": "e16d0d998485698c652f96f6b2ff8826",
    "signature": "3zjYFqRhDsaTLF7FVv4yu+Zie3x/wG8JuRey87Q4Oyb3FzF+2uWs1KaaWIHa
                                                 NUPcN4sF6x4Um+K4SAyamNnFVg=="
  },
  "customer": {
    "ip_address": "85.140.0.68",
    "id": "customer1"
  },
  "payment": {
    "amount": 80000,
    "currency": "KZT"
  },
  "account": {
    "number": "79821234567"
  }
}

Formats of callbacks and requests for additional payment information submission

In order to submit additional payment information (which can be required depending on the payment processing provider), the web service needs to receive the appropriate callback from the payment platform, 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 parameter approval_code—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 provider side).

The following example of the callback fragment contains the clarification_fields array.

{
  "clarification_fields": [
    "approval_code"
  ],
}

The web service needs to submit the requested additional payment information in a request to the /v2/payment/clarification endpoint. 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:

{
  "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, if you receive the clarification_fields array once more, it is recommended to send request for sending a new confirmation code to the customer and send a request with this new confirmation code to the payment platform. If the code is sent after 80 seconds and you have not received the callback with the clarification_fields array from the payment platform, you should expect to receive the final callback with information about the result of payment processing.

The request for sending a new confirmation code to the customer is sent to the /v2/customer/action/resend endpoint, which belongs to the /v2/customer/action/{action_name} request 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 a request to receive another confirmation code

{
  "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.

After sending correct request for sending a new confirmation code to the customer, you should provide the customer with an opportunity to specify the new confirmation code and send a request with this new code to the payment platform.

A callback 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 payment provider, operation status in these notifications may be incorrect, hence it is recommended to disregard it.

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 KZT purchase from account 79821234567 made by the sc-997741 customer 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": "KZT"
            },
            "type": "purchase",
            "account": {
                "number": "79821234567"
            },
            "description": "test payment"
        },
        "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": "KZT"
            },
            "sum_converted": {
                "amount": 80000,
                "currency": "KZT"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1078,
                "payment_id": "118665991",
                "auth_code": ""
            }
        },
        "account": {
            "type": "mTELE2"
        },
        "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": "invoice_93688696",
            "type": "purchase",
            "status": "decline",
            "date": "2019-10-18T07:32:26+0000",
            "method": "mobile",
            "sum": {
                "amount": 30000,
                "currency": "KZT"
            },
            "description": "test payment"
        },
        "account": {
            "number": "79051234567",
            "type": "mTELE2"
        },
        "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": "KZT"
            },
            "sum_converted": {
                "amount": 30000,
                "currency": "KZT"
            },
            "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 the + sign, for example 79031234567
      • bank_id*—ID of the mobile operator; the table below provides the possible values of the parameter corresponding to the mobile operators:

        Table 2. Identifiers of mobile operators
        Mobile operator bank_id
        MTN 611
        M-Pesa 640
        Tigo 612
        Vodafone 613
    • 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, identifier and customer IP address, mobile number (for crediting), 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"
    },
    "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 Bulk payments 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 via support@ecommpay.com.

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 emulator of Payment Page 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 on the emulator page.
  3. Specify a random phone number in the data entry field (10 digits) 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.

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, for instance you can use the analytic panels on the Analytics tab to this end.

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 and XLS formats—by using the tools on the Payments tab. You can perform export as a one-time download to your local computer or have payment data regularly exported and delivered to email addresses you specify.
  • 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 using the /operations/get queries.

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