MTS Money 2

To accept payments with this alternative payment method you should send:

A service activation check request to clarify if the MTS Money service is already activated for the customer's phone number.
A payment request for the amount indicated by the customer.

MTS Money payment scheme

Stage	Description
1	The customer chooses MTS Money as a payment method.
2	The merchant sends a check request to clarify if the service is activated for the customer's phone number.
3	The bePaid system sends a check request to the MTS Money system.
4	MTS Money notifies bePaid of the service activation status.
5	bePaid sends a response with the check result set as the value of the `service_activated` parameter to the merchant.
6	The customer indicates a required payment amount, accepts the Terms of Service, if needed, and selects "Pay" to complete a payment operation.
7	The merchant sends a payment request.
8	bePaid sends a response with the `pending` transaction status which means that the payment request is being processed.
9	bePaid sends a payment request to MTS Money.
10	After the payment request is processed, MTS Money notifies bePaid of the payment status.
11	The bePaid system sends a notification of the transaction status to the merchant.

Service activation check

Request

API v.2API v.3

To check if the customer has already activated the MTS Money service, send a POST request to https://api.bepaid.by/beyag/gateways/mts_money_widget/check_service with the X-API-Version: 2 header and the following parameters:

Parameter	Type	Description
customer	object	Information about the customer.
phone * required	string	The customer's full mobile phone number, including the country code, but without + sign. For example, 375291112233.

Example of the check request

{
    "request":{
    "test": true,
    "customer":{
        "phone":"375295222222"
        }
    }
}

To check if the customer has already activated the MTS Money service, send a POST request to https://api.bepaid.by/beyag/gateways/mts_money_widget/check_service with the X-API-Version: 3 header and the following parameters:

Parameter	Type	Description
customer	object	Information about the customer.
phone * required	string	The customer's full mobile phone number, including the country code, but without + sign. For example, 375291112233.

Example of the check request

{
    "request":{
    "test": true,
    "customer":{
        "phone":"375295222222"
        }
    }
}

Response

API v.2API v.3

The check response contains the following parameters:

Parameter	Type	Description
service_activated * required	boolean	The service activation check result. Possible values: `true` - the MTS Money service is already activated. The merchant does not need to request the customer's consent to the Terms of Service; `false` - the MTS Money service is not yet activated. For the service activation, the merchant should request the customer's consent to the Terms of Service; `null` - The submitted mobile phone number doesn't belong to MTS operator. Service check failed.
message * required	string	Message from the MTS system.
validation * required	object	Mobile operator check result for the submitted phone number.
operator	string	Mobile operator of the submitted phone number. Possible values: `mts` - MTS mobile operator, `other` - mobile operator other than MTS; `null` - Invalid format of the submitted phone number.
message	string	Message with the result of the mobile operator check.

Example of the successful check response in API v.2

{
    "service_activated": true,
    "message": "Request successfully processed",
    "validation": {
        "operator": "mts",    
        "message": "Request successfully processed" 
    }
}

Example of the check response in API v.2. Phone number doesn't belong to MTS. Service activation failed.

{
    "service_activated": false,
    "message": "Request successfully processed",
    "validation": {
        "operator": "mts",
        "message": "Request successfully processed"
    },
    "error_code": "service_not_activated"
}

Example of the check response in API v.2. MTS Money service is not active. Phone number belongs to MTS.

{
    "service_activated": null,
    "message": null,
    "validation": {
        "operator": "other",
        "message": "Request successfully processed"
    },
    "error_code": "account_not_found"
}

The check response contains the following parameters:

Parameter	Type	Description
code * required	string	Code of the processed transaction.
status * required	string	Service check status.
message * required	string	Message from the MTS system.
friendly message * required	string	Message for the customer.

Example of the check response in API v.3

{
    "code": "S.0000",
    "status": "successful",
    "message": "The operation was successfully processed",
    "friendly_message": "Successfully processed"       
}

Example of the check response in API v.3. Phone number doesn't belong to MTS. Service activation failed.

{
    "code": "F.0213",
    "status": "failed",
    "message": "Not allowed: Сontact the payment service provider for details.",
    "friendly_message": "Not allowed: Failed to complete the transaction. Contact the merchant for details or use another payment method."
}

Example of the check response in API v.3. MTS Money service is not active. Phone number belongs to MTS.

{
    "code": "F.0202",
    "status": "failed",
    "message": "Account ID not found: Failed to complete the transaction. Check the request parameters.",
    "friendly_message": "Account ID not found: Failed to complete the transaction. Contact the payment method provider for details."        
}

Payment

Request

Send a payment request with the following parameters:

Parameter	Type	Description
return_url * required	string	URL to return the customer to when the transaction is completed.
notification_url	string	A URL to get webhook notifications. If the URL is not set, no notifications are sent out.
method	object	A section of the payment method information.
type * required	string	`mts_money`
confirm_agreement * required	string	Possible values: `already_accepted` - the MTS Money service is already activated; `accept` - the MTS Money service is not activated, but the customer agrees on its activation and accepts the Terms of Service; `decline` - the MTS Money service is not activated, and the customer does not agree on its activation and does not accept the Terms of Service to complete a payment transaction.
customer	object	A section of the customer details.
phone * required	string	The customer's full mobile phone number, including the country code, but without + sign. For example, 375291112233.

Example of the payment request

{
  "request": {
    "amount": 100,
    "currency": "BYN",
    "description": "description",
    "test": true,
    "expired_at": "2025-01-01T15:00:00+01:00",
    "tracking_id": "your_uniq_number",
    "return_url": "https://your_shop_URL.by/",
    "customer": {
      "phone": "375295222222"
    },
    "method": {
      "type": "mts_money",
      "confirm_agreement": "accept"
    }
  }
}

Response

The mts_money response section will have the parameters copied from a request. The transaction status will be set as pending while MTS Money is processing the payment.

Example of the payment response with the pending transaction status

{
  "transaction": {
    "uid": "8c5ba7da-a4de-4322-8eed-0f4acaf0b579",
    "type": "payment",
    "status": "pending",
    "amount": 100,
    "currency": "BYN",
    "description": "description",
    "created_at": "2024-05-17T11:25:30Z",
    "updated_at": "2024-05-17T11:25:30Z",
    "method_type": "mts_money",
    "receipt_url": "https://merchant.bepaid.by/customer/transactions/8c5ba7da-a4de-4322-8eed-0f4acaf0b579/83c4c06deb03de7a866885d41e747f1ba3f051f76dbfd5a14ab9c7d62aa7d068",
    "payment": {
      "status": "pending",
      "gateway_id": 3989,
      "message": "Transaction was initialized."
    },
    "mts_money": {
      "type": "mts_money",
      "confirm_agreement": "accept"
    },
    "customer": {
      "phone": "375295222222",
      "email": null,
      "ip": null
    },
    "manually_corrected_at": null,
    "message": "Transaction was initialized.",
    "tracking_id": "your_uniq_number",
    "test": true,
    "billing_address": {
      "phone": "375295222222"
    },
    "additional_data": {
      "payment_method": {
        "type": "alternative"
      }
    },
    "gateway": {
      "iframe": false
    }
  }
}

Notification of the final payment status

Once MTS Money processes the payment and notifies bePaid, you get the notification of the final payment status to the notification URL set in the payment request or in your bePaid back office.

Example of the notification

{
    "transaction": {
        "uid": "d5ac59da-09bf-4f82-826c-f9f96d3fb4ba",
        "type": "payment",
        "status": "successful",
        "amount": 100,
        "currency": "BYN",
        "description": "description",
        "created_at": "2022-03-20T11:44:30Z",
        "updated_at": "2022-03-20T11:44:36Z",
        "method_type": "mts_money",
        "receipt_url": "https://merchant.bepaid.by/customer/transactions/d5ac59da-09bf-4f82-826c-f9f96d3fb4ba/0abb8ceeea66e8bc323cdfa5268efc67905de11cf775a525acf70ba73cafd112?language=en",
        "payment": {
            "status": "successful",
            "gateway_id": 395,
            "message": "Transaction was successfully processed."
        },
        "mts_money": {
            "type": "mts_money",
            "confirm_agreement": "accept"
        },
        "customer": {
            "phone": "375295222222",
            "last_name": "Doe",
            "first_name": "John",
            "ip": "127.0.0.1"
        },
        "message": "Transaction was successfully processed.",
        "tracking_id": "your_uniq_number",
        "test": true,
        "language": "en",
        "paid_at": "2022-03-20T11:44:36Z",
        "billing_address": {
            "phone": "375295222222",
            "last_name": "Doe",
            "first_name": "John",
            "ip": "127.0.0.1"
        },
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        }
    }
}

Testing

To test MTS Money payments, add test: true to the request parameters and use the following test phone numbers:

Phone number	Check request result	Payment request result
375295222222	Service activated	Successful payment
375295111111	Service inactive	Failed payment
375444111111	Invalid phone number	Invalid phone number
375290000000	Phone number belongs to MTS. MTS Money service is activated	Insufficient funds