Оплата

  1. Пользователь вводит сумму и номер своего кошелька Mpesa.
  2. На телефон пользователя приходит пуш-уведомление с запросом на оплату.
  3. Пользователь подтверждает оплату.
  4. Paykassma отправляет постбек на сторону мерчанта.
  5. Средства начисляются на баланс пользователя на платформе мерчанта.

Интеграция через платежное окно (plugin)

Пример ссылки на открытие платежного окна Mpesa:

https://plugin.{URL_сервера}/?
label=label
&currency_code=KES
&lang=en
&wallet_type=mpesa
&custom_transaction_id=custom_transaction_id
&fixed_amount=fixed_amount
&payment_url_success_id=2
&payment_url_pending_id=3
&payment_url_fail_id=1
&success_url=hash
&fail_url=hash
&pending_url=hash


wallet_type=mpesa
currency_code=KES
Доступные языки (lang): en, ur (Урду)

Обратите внимание на описание параметров payment_url_success_id / payment_url_fail_id / payment_url_pending_id и success_url fail_url / pending_url

Для использования payment_url_success_id / payment_url_fail_idpayment_url_pending_id необходимо передать URL'ы саппорту Paykassma, и использовать полученные ID в параметрах.

Для использования success_url / fail_url / pending_url необходимо использовать хеширование URL'ов (подробнее про хеширование см. здесь).

Описание всех параметров плагина смотрите здесь.

Интеграция через клиентский API

Создание платежа

URL: http://api.{URL_сервера}/api/v1/payment/create/mpesa?secret={ pluginapi_secret }

Request method:
POST

Format:
JSON

Parameters:

NameTypeRequiredDescription
secretstringyesКлюч доступа.

Body:

Name

Type

Required

Max Length

Description

amount

float 

yes

ограничена min и max.
депозитом

Сумма платежа.
phone_numberstringyes12

MSISDN (12-значный номер мобильного телефона), например 254XXXXXXXXX.

currencystringyes3Код валюты.
labelstring yes190Это уникальный идентификатор (ID) пользователя, осуществляющего платеж.
custom_transaction_idstringyes190Идентификатор транзакции в системе Клиента. Должен быть уникальным.
Request
{
    "amount": 1000,
    "phone_number": "254712344321",
    "currency": "KES",
    "label": "test",
    "custom_transaction_id": "01abc0095689"
}
Response Success
{
    "status": "ok",
    "data": {        
        "order_id": "e5c0637c10d326f7",
        "message": "Success. Request accepted for processing"    
     }
}
Response Fail
{
    'status': 'fail',
    'message': 'MESSAGE'
}

Постбек депозита

Общую документацию по постбекам смотрите здесь.

Пример постбека на депозит Mpesa

{
  "signature": "942c4322170f68bb7939050d892f2437d62d9e79",
  "wallet_type": "mpesa",
  "amount": 3000,
  "currency_code": "KES",
  "label": "1507315922",
  "converted_amount": {
    "USD": 20.34, "INR": 1694, "EUR": 19.24, "IDR": 315099.01, "MYR": 95.39, "VND": 495945.99, "SGD": 27.83, "THB": 739.92, "NGN": 15855.07, "TRY": 555.09, "AED": 74.7, "CAD": 27.49, "AUD": 31.79, "BDT": 2242.53, "AFN": 1587.43, "ALL": 2040.8, "AMD": 7883.01, "AOA": 16850.25, "ARS": 7118.43, "AWG": 36.66, "AZN": 34.58, "BAM": 37.54, "BBD": 40.68, "BGN": 37.64, "BHD": 7.67, "BIF": 57735.18, "BMD": 20.34, "BND": 27.82, "BOB": 140.54, "BRL": 101.45, "BSD": 20.34, "BTC": 0.00077816, "BTN": 1692.31, "BWP": 278.61, "BYN": 51.34, "BZD": 41, "CDF": 50602.47, "CHF": 18.62, "CLF": 0.67, "CLP": 18363.25, "CNH": 148.71, "CNY": 148.71, "COP": 82715.9, "CRC": 10952.3, "CUC": 20.34, "CUP": 523.72, "CVE": 2121.25, "CZK": 469.95, "DJF": 3621.57, "DKK": 143.48, "DOP": 1153.84, "DZD": 2794.36, "EGP": 628.85, "ERN": 305.08, "ETB": 1124.53, "FJD": 46.09, "FKP": 16.72, "GBP": 16.72, "GEL": 54.3, "GGP": 16.72, "GHS": 234.81, "GIP": 16.72, "GMD": 1323.04, "GNF": 175189.88, "GTQ": 159.85, "GYD": 4255.11, "HKD": 159.08, "HNL": 504.3, "HRK": 144.96, "HTG": 2735.62, "HUF": 7513.95, "ILS": 77.82, "IMP": 16.72, "IQD": 26639.37, "IRR": 859311.93, "ISK": 2791.7, "JEP": 16.72, "JMD": 3142.77, "JOD": 14.44, "JPY": 3031.35, "KES": 3000, "KGS": 1804.25, "KHR": 83754.5, "KMF": 9476.84, "KPW": 18304.87, "KRW": 27540.77, "KWD": 6.29, "KYD": 16.95, "KZT": 9753.57, "LAK": 409713.54, "LBP": 306020.24, "LKR": 6591.09, "LRD": 3793.18, "LSL": 386.85, "LYD": 99.2, "MAD": 208.75, "MDL": 369.46, "MGA": 92115.21, "MKD": 1183.98, "MMK": 42712.38, "MNT": 70168.67, "MOP": 163.84, "MRO": 0, "MRU": 775.52, "MUR": 909.25, "MVR": 314.44, "MWK": 22300.63, "MXN": 356.71, "MZN": 1298.63, "NAD": 387.25, "NIO": 743.69, "NOK": 220.08, "NPR": 2707.73, "NZD": 34.18, "OMR": 7.83, "PAB": 20.34, "PEN": 76.82, "PGK": 73.95, "PHP": 1163.56, "PKR": 5855.35, "PLN": 88.66, "PYG": 148239.26, "QAR": 74.05, "RON": 95.67, "RSD": 2256.75, "RUB": 1964.72, "RWF": 24654.31, "SAR": 76.29, "SBD": 170.51, "SCR": 273.52, "SDG": 12233.75, "SEK": 223.65, "SHP": 16.72, "SLL": 426493.29, "SOS": 11607.73, "SRD": 777.92, "SSP": 2649.32, "STD": 453183.83, "STN": 472.42, "SVC": 177.95, "SYP": 51101.7, "SZL": 385.95, "TJS": 223.42, "TMT": 71.19, "TND": 64.6, "TOP": 48.59, "TTD": 137.97, "TWD": 655.07, "TZS": 50950.12, "UAH": 751.2, "UGX": 76661.49, "UYU": 775.64, "UZS": 248276.03, "VEF": 0, "VES": 692.55, "VUV": 2414.66, "WST": 55.29, "XAF": 12622.91, "XAG": 0.89, "XAU": 0.01, "XCD": 54.97, "XDR": 15.46, "XOF": 12622.91, "XPD": 0.02, "XPF": 2296.36, "XPT": 0.02, "YER": 5091.81, "ZAR": 387.87, "ZMW": 427.62, "ZWL": 6549.08, "ETH": 0.0128193, "LTC": 0.32079446, "DOGE": 339.50676297, "DASH": 0.76821266, "BCH": 0.09552538, "ZEC": 0.78053001, "ETC": 1.35808119, "XRP": 40.73720295, "TRX": 241.33637078, "XLM": 182.51062761, "WAVES": 13.47218958, "USDT": 20.34363973, "USDTTRC20": 0, "USDT20": 0
  },
  "direction": "ingoing",
  "created_datetime": "2023-09-26 22:00:54",
  "access_key": "TA25Ea9sjPUFJvIG",
  "additional_data": [
    {
      "activated_datetime": "2023-09-27 01:00:52",
      "exchanger_identifier": null,
      "comment": "",
      "amount": "3000",
      "currency_code": "KES",
      "wallet_type": "mpesa",
      "stockpiling_id": 4822019,
      "transaction_id": "RIR7U1Y6OH",
      "transaction_type": 0,
      "plugin_custom_order_id": "5593665234",
      "withdrawal_id": null,
      "withdrawal_status": null,
      "account_number": "",
      "account_name": "",
      "account_email": "",
      "bank_details": {
        "bank_code": "",
        "branch_code": ""
      }
    }
  ]
}
Сервер Paykassma ожидает ответ в json {"status":"ok"} код ответа 200, в противном случае, при получении отличающегося ответа, Paykassma будет пересылать постбек с определенной периодичностью.
На повторные постбеки необходимо также отвечать {"status":"ok"} код ответа 200.

Выводы / выплаты пользователям

Общую документацию по выводам смотрите здесь.

Создание вывода

URL: https://api.{URL_сервера}/v2/withdrawal/create

Request method:

POST

Format:
JSON

Parameters:

Name

Type

Required

Description

withdrawal_idstring(1-36) yes Идентификатор вывода, если параметр не передается, то система генерирует withdrawal_id.
payment_systemstring yesПлатежная система.
amount

int


yes

Дополнительные требования:

  1. amount >= величина установленного минимального значения;
  2. amount <= величина установленного максимального значения. 
currency_codestring(3) yesКод валюты

is_test

booleanyes

Параметр is_test может принимать одно из двух значений:

  • true - если Вывод тестовый;
  • false - если вывод реальный. 

label

string(1-36)

yes

Label пользователя, для которого проводится вывод.

account_numberstring 

yes

MSISDN (12-значный номер мобильного телефона), например 2547XXXXXXXX.

signaturestringyesПодпись, формируемая с private_key.


Request
{
  "withdrawal_id": "85858053",
  "payment_system": "mpesa",
  "amount": 1000,
  "currency_code": "KES",
  "label": "160496026",
  "comment": "withdrawal",
  "account_number": "254724653314",
  "is_test": true,
  "signature": "2266a77c54925494335c12d365bdbf67f7e6e9c6"
}
Response Success
{
    "status": "ok"
}
Response Fail
{
    'status': 'fail',
    'message': 'MESSAGE'
}

*Если при попытке создания заявки на вывод сумма балансов счетов в валюте заявки будет меньше, чем общая сумма новой и еще незавершенных заявок, то отобразится ошибка 'Недостаточный баланс' (для настройки данного функционала обратитесь в ТП Paykassma).

Response Fail (при недостаточном балансе)
{
    "status": "fail",
    "message": {
        "withdrawals_sum_amount": [
            "Insufficient balance"
        ]
    }
}

Пример постбека на вывод Mpesa

{
    "signature": "d386dd6214876de4e0ec751397473b9f76df4ec1",
    "wallet_type": "mpesa",
    "amount": 15944,
    "currency_code": "KES",
    "label": "2566752",
    "converted_amount": {"USD": 110.57, "INR": 9195, "EUR": 101.54, "IDR": 1694022.35, "MYR": 514.42, "VND": 2638444.51, "SGD": 150.22, "THB": 3908.48, "NGN": 84686.74, "TRY": 2997.05, "AED": 406.12, "CAD": 150.03, "AUD": 173.38, "BDT": 12070.53, "AFN": 9298.06, "ALL": 10757.78, "AMD": 42637.71, "AOA": 91550.85, "ARS": 38596.79, "AWG": 199.02, "AZN": 187.97, "BAM": 198.55, "BBD": 221.14, "BGN": 198.55, "BHD": 41.68, "BIF": 312645.37, "BMD": 110.57, "BND": 149.78, "BOB": 763.96, "BRL": 549.56, "BSD": 110.57, "BTC": 0.0042204, "BTN": 9169.03, "BWP": 1500.44, "BYN": 279.04, "BZD": 222.84, "CDF": 273599.99, "CHF": 97.53, "CLF": 3.47, "CLP": 96146.66, "CNH": 808.25, "CNY": 805.11, "COP": 453374.23, "CRC": 59087.64, "CUC": 110.57, "CUP": 2847.14, "CVE": 11193.91, "CZK": 2442.59, "DJF": 19635.67, "DKK": 757.76, "DOP": 6258.6, "DZD": 15074.93, "EGP": 3416.57, "ERN": 1658.53, "ETB": 6086.02, "FJD": 251.25, "FKP": 86.83, "GBP": 86.83, "GEL": 289.69, "GGP": 86.83, "GHS": 1247.76, "GIP": 86.83, "GMD": 6694.93, "GNF": 956971.7, "GTQ": 865.65, "GYD": 23095.41, "HKD": 865.96, "HNL": 2713.89, "HRK": 766.21, "HTG": 14998.31, "HUF": 38880.36, "ILS": 419.61, "IMP": 86.83, "IQD": 144440.06, "IRR": 4674289.85, "ISK": 14617.18, "JEP": 86.83, "JMD": 17100.58, "JOD": 78.26, "JPY": 16078.34, "KES": 15944, "KGS": 9759.9, "KHR": 457201.38, "KMF": 50032.29, "KPW": 99511.79, "KRW": 148179.69, "KWD": 34.05, "KYD": 92.13, "KZT": 50075.95, "LAK": 2151252.07, "LBP": 1662442.92, "LKR": 35618.7, "LRD": 20593.41, "LSL": 2103.12, "LYD": 531.96, "MAD": 1087.11, "MDL": 1958.6, "MGA": 499266.92, "MKD": 6255.3, "MMK": 232155.2, "MNT": 381461.86, "MOP": 889.54, "MRO": 0, "MRU": 4192.76, "MUR": 5023.45, "MVR": 1699.99, "MWK": 119608.81, "MXN": 1886.09, "MZN": 7062.57, "NAD": 2112.97, "NIO": 4042.39, "NOK": 1179.16, "NPR": 14670.41, "NZD": 186.71, "OMR": 42.57, "PAB": 110.57, "PEN": 410.2, "PGK": 402.22, "PHP": 6215.29, "PKR": 32752.97, "PLN": 453.51, "PYG": 800774.3, "QAR": 402.61, "RON": 502.97, "RSD": 11916.16, "RUB": 10404.62, "RWF": 130481.49, "SAR": 414.66, "SBD": 925.41, "SCR": 1498.33, "SDG": 66451.76, "SEK": 1212.35, "SHP": 86.83, "SLL": 2318569.39, "SOS": 62799.14, "SRD": 4223.78, "SSP": 14402.67, "STD": 2463668.63, "STN": 2487.2, "SVC": 967.3, "SYP": 277807.06, "SZL": 2102.65, "TJS": 1211.42, "TMT": 386.99, "TND": 341.27, "TOP": 264.32, "TTD": 747.89, "TWD": 3528.36, "TZS": 276974.48, "UAH": 4072.85, "UGX": 411859.64, "UYU": 4173.13, "UZS": 1331920.8, "VEF": 0, "VES": 3490.9, "VUV": 13126.93, "WST": 300.58, "XAF": 66603.86, "XAG": 4.86, "XAU": 0.06, "XCD": 298.82, "XDR": 82.69, "XOF": 66603.86, "XPD": 0.09, "XPF": 12116.58, "XPT": 0.12, "YER": 27680.86, "ZAR": 2107.66, "ZMW": 2136.66, "ZWL": 35603.11, "ETH": 0.06574301, "LTC": 1.71255144, "DOGE": 1728.85705323, "DASH": 4.15170479, "BCH": 0.58532281, "ZEC": 4.420694, "ETC": 7.08854424, "XRP": 211.91758501, "TRX": 1497.48765233, "XLM": 888.34414391, "WAVES": 71.66334269, "USDT": 110.58938893, "USDTTRC20": 0, "USDT20": 0},
    "direction": "outgoing",
    "created_datetime": "2023-08-19 16:29:01",
    "access_key": "FQ9jMwrNSkFbyMNqYFf6Ed4xeKmjHK",
    "additional_data": [
        {
            "activated_datetime": "",
            "exchanger_identifier": "",
            "comment": "transaction_id=0",
            "amount": "15944",
            "currency_code": "KES",
            "wallet_type": "mpesa",
            "stockpiling_id": null,
            "transaction_id": "",
            "transaction_type": null,
            "plugin_custom_order_id": "",
            "withdrawal_id": "1071050",
            "withdrawal_status": 1,
            "account_number": "254790916213",
            "account_name": "",
            "account_email": "",
            "bank_details": {
                "bank_code": null,
                "branch_code": null
            }
        }
    ]
}
Сервер Paykassma ожидает ответ в json {"status":"ok"} код ответа 200, в противном случае, при получении отличающегося ответа, Paykassma будет пересылать постбек с определенной периодичностью.
На повторные постбеки необходимо также отвечать {"status":"ok"} код ответа 200.

После обработки вывода Paykassma пришлет постбек о результате вывода со статусом (withdrawal_status), подписанный сигнатурой.

Статусы выводов

1SUCCESSСтатус для вывода, когда заявка на вывод была успешно обработана.
5FAILСтатус для вывода, когда заявка на вывод была отклонена.

Создание заявки на выплату в ЛК Paykassma

Для создания заявки на вывод, необходимо перейти на страницу Выводы (Оплаты → Выводы) и выполнить следующие шаги:

  1. Нажмите на кнопку "Добавить заявку на вывод".                                            
  2.  Выберите из списка нужную ПС.                                                                                                        
  3.  Заполните поля для создания заявки в следующем окне (Cписок полей стандартизирован и не все поля являются обязательными. Для создания заявки по определенной ПС, необходимо заполнить обязательные поля для этой ПС).
    Обязательные поля для выплаты Mpesa:
    - Лейбл (ID пользователя);
    - Сумма;
    - Валюта;
    - Кошелек получателя.                                                                                                                  
  4. После оплаты статус вывода поменяется.

Paykassma не высылает постбек по выводам, созданным вручную.

Оглавление: