MTS Money
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.
| 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
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/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/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
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 belon go MTS. Service activation failed.
{
"service_activated": false,
"message": "Request successfully processed",
"validation": {
"operator": "mts",
"message": "Request successfully processed"
}
}
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": "null",
"message": "Description of the provider's error"
}
}
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 |
|---|---|---|
| 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": "2023-01-01T15:00:00+01:00",
"tracking_id":"your_uniq_number",
"notification_url": "https://notification_url.com",
"ip":"127.0.0.1",
"language":"en",
"return_url": "https://your_shop_URL.by/",
"customer":{
"first_name":"John",
"last_name":"Doe",
"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": "d5ac59da-09bf-4f82-826c-f9f96d3fb4ba",
"type": "payment",
"status": "pending",
"amount": 100,
"currency": "BYN",
"description": "description",
"created_at": "2022-03-20T11:44:30Z",
"updated_at": "2022-03-20T11:44:30Z",
"method_type": "mts_money",
"receipt_url": "https://merchant.bepaid.by/customer/transactions/d5ac59da-09bf-4f82-826c-f9f96d3fb4ba/0abb8ceeea66e8bc323cdfa5268efc67905de11cf775a525acf70ba73cafd112?language=en",
"payment": {
"status": "pending",
"gateway_id": 395,
"message": "Transaction was initialized."
},
"mts_money": {
"type": "mts_money",
"confirm_agreement": "accept"
},
"customer": {
"first_name": "John",
"last_name": "Doe",
"phone": "375295222222",
"ip": "127.0.0.1"
},
"message": "Transaction was initialized.",
"tracking_id": "your_uniq_number",
"test": true,
"language": "en",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"phone": "375295222222",
"ip": "127.0.0.1"
},
"additional_data": {
"payment_method": {
"type": "alternative"
}
}
}
}
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 |