Versions Compared

Old Version 6

changes.mady.by.user christie

Saved on

compared with

New Version 7

changes.mady.by.user christie

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Payment

  1. The user enters the amount and his Mpesa wallet number.
  2. User receives notification to the mobile.
  3. The user confirms the payment.
  4. Paykassma sends a postback to the merchant.
  5. The funds are credited to the user's balance on the merchant's platform.

Payment window integration (plugin)

Example of a link to open a Mpesa payment window:

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


Code Block
wallet_type=mpesa
currency_code=KES
Available languages (lang): en
Info

Pay attention to the description of the parameters payment_url_success_id / payment_url_fail_id/ payment_url_pending_id and success_url / fail_url / pending_url.
To use payment_url_success_id / payment_url_fail_id / payment_url_pending_id you need to send the URLs to Paykassma support and use the received IDs in the parameters.
To use success_url / fail_url / pending_url you must use hashing URLs ( For more details on hashing click here ).

For the description of all the plug-in parameters click here.

API integration

Payment creation

URL: http://api.{ server URL }/api/v1/payment/create/mpesa?secret={ pluginapi_secret }

Request method:
POST

Format:
JSON

Parameters:

NameTypeRequiredDescription
secretstringyesAccess key

Body:

Name

Type

Required

Max Length

Description

amount

float 

yes

is limited to min and max.
deposit

Payment amount
phone_numberstringyes12

MSISDN (12-digit cell phone number), e.g. 2547XXXXXXXX.

currencystringyes3Currency code
labelstring yes190The unique identifier (ID) of the user who makes the payment.
custom_transaction_idstringyes190Transaction identifier in the Client's system. Must be unique.


Code Block
themeDJango
titleRequest
{
    "amount": 1000,
    "phone_number": "254712344321",
    "currency": "KES",
    "label": "test",
    "custom_transaction_id": "01abc0095689"
}


Code Block
themeDJango
titleResponse Success
{
    "status": "ok",
    "data": {        
        "order_id": "e5c0637c10d326f7",
        "message": "Success. Request accepted for processing"    
     }
}


Code Block
themeDJango
titleResponse Fail
{
    'status': 'fail',
    'message': 'MESSAGE'
}

Deposit postback

For the general documentation on post backs click here.

Example of a deposit postback for Mpesa

Code Block
languagephp
themeDJango
collapsetrue
{
  "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": ""
      }
    }
  ]
}


Warning

The Paykassma server is waiting for a response in json {"status": "ok"} response code 200, otherwise, when receiving a different response, Paykassma will forward the postback with a certain frequency.
Repeated postbacks must also be answered with {"status":"ok"} response code 200.

Withdrawals for users

For the general documentation on the withdrawals of funds click here.

Withdrawal request

URL: https://api.{ server URL }/v2/withdrawal/create

Request method:

POST

Format:
JSON

Parameters:

Name

Type

Required

Description

withdrawal_idstringyes Withdrawal ID, if the parameter is not passed, then the system generates withdrawal _id.
payment_systemstring yesPayment system
amount

int


required
Additional requirements:
  1. amount >= The value of the set minimum value
  2. amount <=The value of the set maximum value
currency_codestringyesCurrency code

is_test

booleanyes

The is_test parameter possible values:

true - if Withdrawal is test
false - if Withdrawal is real

label

string

yes

The unique identifier (ID) of the user who makes the payment.

account_numberstring 

yes

MSISDN (12-digit cell phone number), e.g. 2547XXXXXXXX.

signaturestringyesSignature generated with private_key.


Code Block
languagephp
themeDJango
titleRequest
{
"withdrawal_id": "85858053",
"payment_system": "mpesa",
"amount": 1000,
"currency_code": "KES",
"label": "160496026",
"comment": "withdrawal",
"account_number": "254724653314",
"is_test": true,
"signature": "2266a77c54925494335c12d365bdbf67f7e6e9c6"
}


Code Block
languagephp
themeDJango
titleResponse Success
{
    "status": "ok",
}


Code Block
languagephp
themeDJango
titleResponse Fail
{
    'status': 'fail',
    'message': 'MESSAGE'
}

*If, when trying to create a withdrawal request, the amount of account balances in the currency of the request is less than the total amount of new and still incomplete applications, the error message"Insufficient balance" will be displayed (to configure this functionality, contact the TP Paykassma).

Code Block
languagephp
themeDJango
titleResponse Fail (if the balance is insufficient)
{
    "status": "fail",
    "message": {
        "withdrawals_sum_amount": [
            "Insufficient balance"
        ]
    }
}

Example of a postback for a Mpesa withdrawal

Code Block
languagephp
themeDJango
collapsetrue
{
    "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
            }
        }
    ]
}


Warning

The Paykassma server is waiting for a response in json {"status": "ok"} response code 200, otherwise, when receiving a different response, Paykassma will forward the postback with a certain frequency.
Repeated postbacks must also be answered with {"status":"ok"} response code 200.

After processing the withdrawal, Paykassma will send a postback about the withdrawal result with status, signed with a signature.

Withdrawal statuses

1SUCCESSStatus for withdrawal when the withdrawal request has been successfully processed
5FAILStatus for withdrawal when the withdrawal request was rejected

Creating withdrawal request in Paykassma BO

To create a withdrawal request, you need to go to the Withdrawals page Payments  → Withdrawals and perform the following steps.

1. Press the button "Add withdrawal request".

2. Select payment system from list.


3. Fill in the fields to create the request in the next window (the list of fields is standardized and not all fields are required. To create a request for a specific PS, you should fill in the required fields for this PS).
Required fields for bKash payout:
- Label (user ID)
- Amount
- Currency code
- Wallet recipient

4. After payment the withdrawal status will change.

Paykassma does not send postback for withdrawals created manually.

Table of Contents
excludeОглавление: