PesaWay

# Mobile Money Money Transfer

# Business to Business (B2B)

As a PesaWay merchant, you can send money to other businesses through their Tills or Paybills. The Business to Business API is applicable in various use cases such as Supplier Payments.

Alt test Endpoint: https://api.sandbox.pesaway.com/v1/mobile-money/receive-payment/

# Request Parameters

Field Type Description Examples
Amount Number The amount of money being sent to the customer. 30.00
ExternalReference Alpha-Numeric A unique identifier of the transaction generated by the Merchant system. "1234"
AccountNumber Numeric This is the customer mobile where the funds are to be received. Mobile number must include country code eg. 254712345678 123456
Channel Numeric The Paybill or Till number to send the payment to. Code->Channel
Currency Alpha-Numeric The currency being used. "KES"
MerchantCode Alpha-Numeric A unique number assigned through which payment is received or sent 1******2
Reason Alpha-Numeric The reason for payment. "Payment of transportation fee"
ResultsUrl URL This is the URL to be specified in your request that will be used to send notification upon processing of the payment request "https://yourdomain.com/result_url"

# Supported Channels

  1. MPESA Paybill
  2. MPESA Till

# Sample Request

curl --location --request POST 'https://api.sandbox.pesaway.com/api/v1/mobile-money/send-payment/' \
--header 'X-Region: ke' \
--header 'Authorization: Bearer MWU1NzI1YzhhN2Y1YTExMmU5ZWI4NGNlMDdjODc5' \
--header 'Content-Type: application/json' \
--data-raw '{
    "ExternalReference": "1234",
    "Amount": 30,
    "AccountNumber": "12345",
    "Channel": "MPESA Paybill",
    "MerchantCode": "2356426365436",
    "Currency": "KES",
    "Reason": "Payment of transportation fee",
    "ResultsUrl": "https://yourdomain.com/result_url"
  }'

TIP

Alway include the X-Region header on all requests. The right X-Region can be found on the Supported Regions / Countries menu

# Response Parameters

Field Type Description Example
code String This is a status code for either success or failure of the transaction "200.001"
TransactionID String An identifier for the transaction request returned by PesaWay upon successful request submission. This is generated by PesaWay API. "PHY20ADFASFASFS"
OriginatorReference String An identifier for the transaction request from the merchant side. It is the input given as TransactionReference when sending B2C request. "123344"

# Response Sample

{
  "code": "200.001",
  "Status": "Active",
  "TransactionID": "PHYADFADSFWADS",
  "OriginatorReference": "4040359-0f8",
  "ResponseDescription": "Transaction of 50 to 2547*****677 is being processed"
}

# Callback Structure

Field Type Description Example
ReceiverPartyPublicName String This full name of the customer receiving the funds. "John Kym Doe"
ResultCode Numeric The numeric status of the results, sent to the callback url 0 means success, while any other code indicates that an error occurred. field
ResultDesc String This is a message from the API that gives the status of the request processing and usually maps to a specific result code value. "The service request is processed successfully"
TransactionID String This is a unique PesaWay transaction ID for every payment request. Same value is sent to the customer over SMS upon successful processing. PR52
TransactionReceipt String This is a unique transaction ID dependent on the channel for every payment request. Same value is sent to the customer over SMS upon successful processing. QTD6ADFSAs
TransactionAmount Number This is the amount that was transacted. It is usually returned under the ResultParameter array. "10.00"
OriginatorReference Decimal A unique identifier of the transaction generated by the Merchant system. "254******77"
TransactionCompletedDateTime String This is the date and time that the transaction completed PesaWay. "20220305103101"
AccountAvailableFunds Decimal This is the available balance after the transaction. 564.00

# Sample Callback Structure

{
  "ResultType": 0,
  "ResultDesc": "The service request is processed successfully.",
  "Originator": "PW_TEST_01",
  "TransactionID": "PHY0A0AE3JF2",
  "TransactionAmount": "50.00",
  "TransactionReceipt": "QKR3S0JA9H",
  "AccountAvailableFunds": "5.00",
  "ReceiverPartyPublicName": "21234",
  "TransactionCompletedDateTime": "2022-11-27 14:37:49.690634+00:00"
}

# Business to Customer (B2C)

As a PesaWay merchant, you can send money to your customers through various networks. The Business to Customer API is applicable in various use cases such as Salary Payments, Promotional Payments, winnings, financial institutions withdrawal of funds, loan disbursements etc.

POST https://api.sandbox.pesaway.com/api/v1/mobile-money/send-payment/

# Request Parameters

Field Type Description Examples
Amount Number Payout amount; with FX, the original price in PricingCurrency, otherwise the local payout amount. 30.00
ExternalReference Alpha-Numeric A unique identifier of the transaction generated by the Merchant system. "1234"
PhoneNumber Numeric This is the customer mobile where the funds are to be received. Mobile number must include country code eg. 254712345678 2547*******8
Channel Numeric PesaWay account or other bank accounts where money is being transferred. Code->Channel
Currency Alpha-Numeric The currency being used. "KES"
Reason Alpha-Numeric The reason for payment. "Payment of transportation fee"
MerchantCode Alpha-Numeric A unique number assigned through which payment is received 1******2
ResultsUrl URL This is the URL to be specified in your request that will be used to send notification upon processing of the payment request "https://yourdomain.com/result_url"

# FX payout fields and funding

Field Requirement Meaning
MerchantCode Required with FX Local-currency wallet to debit.
FxQuoteID Required with FX Fresh quote created with Flow: "disbursement" for that wallet.
PricingCurrency Required with FX Currency of the original requested price, for example USD.
Amount Required Original pricing amount, matching the quote.
Currency Match the wallet Local currency paid to the recipient, for example KES, UGX or TZS.

The aliases fx_quote_id and pricing_currency are also accepted. Omit the FX fields for ordinary local-currency payouts.

The funding wallet must use the recipient's local currency. A USD-priced payout funded from a KES wallet is supported; directly debiting a USD wallet to pay a KES recipient is not supported by this flow. The local wallet must cover the converted principal plus payout fees.

See FX payouts for the full request, currency rules, quote expiry and retry guidance.

# Supported Channels

# Kenya

Network Code
MPESA MPESA
Airtel Airtel

# Uganda

Network Code
MTN MOMO-UG
Airtel Airtel-UG

# Tanzania

Network Code
Vodacom MPESA Vodacom MPESA
Tigo / Yas Tigo PESA
Airtel Airtel
Halo Halo PESA

# Ghana

Network Code
MTN Ghana MTN Ghana
AirtelTigo AirtelTigo
Vodafone Cash Vodafone Cash

# Zambia

Network Code
Zamtel Zamtel Zambia
Airtel Airtel Zambia
MTN MTN Zambia

# Cameroon

Coming soon!

# Sample Request

curl --location --request POST 'https://api.sandbox.pesaway.com/api/v1/mobile-money/send-payment/' \
--header 'X-Region: ke' \
--header 'Authorization: Bearer MWU1NzI1YzhhN2Y1YTExMmU5ZWI4NGNlMDdjODc5' \
--header 'Content-Type: application/json' \
--data-raw '{
    "ExternalReference": "1234",
    "Amount": 30,
    "PhoneNumber": "25471***8",
    "MerchantCode": "2356426365436",
    "Channel": "MPESA",
    "Currency": "KES",
    "Reason": "Payment of transportation fee",
    "ResultsUrl": "https://yourdomain.com/result_url"
  }'

TIP

Alway include the X-Region header on all requests. The right X-Region can be found on the Supported Regions / Countries menu

# Response Parameters

Field Type Description Example
code String This is a status code for either success or failure of the transaction "200.001"
TransactionID String An identifier for the transaction request returned by PesaWay upon successful request submission. This is generated by PesaWay API. "PHY20ADFASFASFS"
OriginatorReference String An identifier for the transaction request from the merchant side. It is the input given as TransactionReference when sending B2C request. "123344"

# Response Sample

{
  "code": "200.001",
  "Status": "Active",
  "TransactionID": "PHYADFADSFWADS",
  "OriginatorReference": "4040359-0f8",
  "ResponseDescription": "Transaction of 50 to 2547*****677 is being processed"
}

# Callback Structure

Field Type Description Example
ReceiverPartyPublicName String This full name of the customer receiving the funds. "John Kym Doe"
ResultCode Numeric The numeric status of the results, sent to the callback url 0 means success, while any other code indicates that an error occurred. field
ResultDesc String This is a message from the API that gives the status of the request processing and usually maps to a specific result code value. "The service request is processed successfully"
TransactionID String This is a unique PesaWay transaction ID for every payment request. Same value is sent to the customer over SMS upon successful processing. PR52
TransactionReceipt String This is a unique transaction ID dependent on the channel for every payment request. Same value is sent to the customer over SMS upon successful processing. QTD6ADFSAs
TransactionAmount Number This is the amount that was transacted. It is usually returned under the ResultParameter array. "10.00"
OriginatorReference Decimal A unique identifier of the transaction generated by the Merchant system. "254******77"
TransactionCompletedDateTime String This is the date and time that the transaction completed PesaWay. "20220305103101"
AccountAvailableFunds Decimal This is the available balance after the transaction. 564.00

# Sample Callback Structure

{
  "ResultType": 0,
  "ResultDesc": "The service request is processed successfully.",
  "Originator": "PW_TEST_01",
  "TransactionID": "PHY0A0AE3JF2",
  "TransactionAmount": "50.00",
  "TransactionReceipt": "QKR3S0JA9H",
  "AccountAvailableFunds": "5.00",
  "ReceiverPartyPublicName": "254700xxxxxx - John Doe",
  "TransactionCompletedDateTime": "2022-11-27 14:37:49.690634+00:00"
}

# Customer to Business (C2B)

As a PesaWay merchant, you can receive money from your customers through various networks. The Customer to Business API is applicable in various use cases such as ticket payments, invoicing, loan repayments etc.

POST https://api.sandbox.pesaway.com/api/v1/mobile-money/receive-payment/

# Request Parameters

Field Type Description Examples
Amount Number Collection amount. With FX, the original price in PricingCurrency; otherwise the local currency amount. 30.00
ExternalReference Alpha-Numeric A unique identifier of the transaction generated by the Merchant system. "1234"
PhoneNumber String This is the customer mobile from where the funds are to be received. Mobile number must include country code eg. 254712345678 2547*******8
Channel String Collection method e.g. MPESA Code->Channel
Currency Alpha-Numeric The currency being used. "KES"
MerchantCode Alpha-Numeric A unique number assigned through which payment is received 1******2
Reason Alpha-Numeric The reason for payment. "Payment of transportation fee"
ResultsUrl URL This is the URL to be specified in your request that will be used to send notification upon processing of the payment request "https://yourdomain.com/result_url"

# FX collections: foreign prices, local payments

For goods priced in a different currency from the customer payment, first create an FX quote for your local-currency merchant account, then include these fields in the collection request:

Field Requirement Description
FxQuoteID Required with FX Fresh quote ID for the same merchant and collection flow.
PricingCurrency Required with FX Price currency, for example USD. Lowercase pricing_currency is also accepted.
Amount Required Original pricing amount, for example 10.00 USD, not the converted local amount.
Currency Local payment currency The quote’s PayableCurrency, for example KES, UGX or TZS.
MerchantCode Required with FX The same local-currency account used to create the quote.

The alias fx_quote_id is also accepted. Omit both FX fields for ordinary local-currency collections.

Follow the complete FX collection integration guide for copyable requests, fees, expiry, completion checks, safe retries and troubleshooting. A successful initiation means processing; completed callback/query amounts are in the merchant account currency. Choose an enabled channel for that currency and market.

# Supported Channels

# Kenya

Network Code
MPESA MPESA
Airtel Airtel

# Uganda

Network Code
MTN MOMO-UG
Airtel Airtel-UG

# Tanzania

Network Code
Vodacom MPESA Vodacom MPESA
Tigo / Yas Tigo PESA
Airtel Airtel
Halo Halo PESA

# Ghana

Network Code
MTN Ghana MTN Ghana
AirtelTigo AirtelTigo
Vodafone Cash Vodafone Cash

# Zambia

Network Code
Zamtel Zamtel Zambia
Airtel Airtel Zambia
MTN MTN Zambia

# Cameroon

Coming soon!

# Sample Request

curl --location --request POST 'https://api.sandbox.pesaway.com/api/v1/mobile-money/receive-payment/' \
--header 'X-Region: ke' \
--header 'Authorization: Bearer MWU1NzI1YzhhN2Y1YTExMmU5ZWI4NGNlMDdjODc5' \
--header 'Content-Type: application/json' \
--data-raw '{
    "ExternalReference": "1234",
    "Amount": 30,
    "PhoneNumber": "25471***8",
    "MerchantCode": "2356426365436",
    "Channel": "MPESA",
    "Currency": "KES",
    "Reason": "Payment of transportation fee",
    "ResultsUrl": "https://yourdomain.com/result_url"
  }'

TIP

Alway include the X-Region header on all requests. The right X-Region can be found on the Supported Regions / Countries menu

# Response Parameters

Field Type Description Example
code String This is a status code for either success or failure of the transaction "200.001"
TransactionID String An identifier for the transaction request returned by PesaWay upon successful request submission. This is generated by PesaWay API. "PHY20ADFASFASFS"
ResponseDescription String This is a message from the API that gives the status of the request processing and usually maps to a specific result code value. "The service request is processed successfully"
OriginatorReference String An identifier for the transaction request from the merchant side. It is the input given as ExternalReference when sending C2B request. "123344"

# Response Sample

{
  "code": "200.001",
  "TransactionID": "PHY01ADFDAS",
  "OriginatorReference": "1234445",
  "ResponseDescription": "Success. Request accepted for processing"
}

# Callback Structure

Field Type Description Example
ResultCode Numeric The numeric status of the results, sent to the callback url 0 means success, while any other code indicates that an error occurred. field
ResultDesc String This is a message from the API that gives the status of the request processing and usually maps to a specific result code value. "The service request is processed successfully"
TransactionID String This is a unique PesaWay transaction ID for every payment request. Same value is sent to the customer over SMS upon successful processing. PR52
TransactionReceipt String This is a unique transaction ID dependent on the channel for every payment request. Same value is sent to the customer over SMS upon successful processing. QTD6ADFSAs
TransactionAmount Number This is the amount that was transacted. It is usually returned under the ResultParameter array. "10.00"
OriginatorReference Decimal A unique identifier of the transaction generated by the Merchant system. "254******77"
TransactionCompletedDateTime String This is the date and time that the transaction completed PesaWay. "20220305103101"
AccountAvailableFunds Decimal This is the available balance after the transaction. 564.00

# Sample Callback Structure

{
  "ResultCode": 0,
  "ResultDesc": "The service request is processed successfully.",
  "TransactionID": "PHYD5AD5ASDF5",
  "TransactionAmount": 20,
  "TransactionReceipt": "NLJ7RT61SV",
  "OriginatorReference": "123455",
  "TransactionCompletedDateTime": "2022-11-27 14:37:49.690634+00:00",
  "PhoneNumber": "254700xxxxxx"
}

split: true code:

  • python
  • curl
  • java
  • csharp

# Authorize Transaction via OTP

There are specific payment methods that require additional transaction authorization via a One Time Password (OTP). When this is enabled for a payment method, the OTP is sent to the end user after the /receive-payment/ request. The OTP should then be submitted as follows:

Test Endpoint:

https://api.sandbox.pesaway.com/api/v1/mobile-money/authorize-transaction/

# Request Parameters

Request Parameters Field Description Example
TransactionID A transaction reference for the target transaction PHYD5AD5ASDF5
OTP A unique code for authorizing the transaction. This is sent directly to the end user 12345

# Request Sample

curl --location --request GET 'https://api.sandbox.pesaway.com/api/v1/mobile-money/authorize-transaction/' \
--header 'X-Region: ke' \
--data-raw '{
    "TransactionID": "PHYD5AD5ASDF5",
    "OTP": "12345"
  }'

# Response Sample

{
  "ResultCode": "0",
  "OriginatorReference": "09876",
  "TransactionID": "PHYD5AD5ASDF5",
  "ResponseDescription": "Success. Transaction authorised successfully."
}

# Response Parameters

Response Parameters Field Type Description
ResultCode A code representation of the results .e.g. 0
OriginatorReference A unique identifier of the transaction generated by the Merchant system.
TransactionID A transaction reference for the target transaction
ResultDescription A sentense describing whether the transaction filed or succeeded
ResultCode A code representation of the results .e.g. 0

# Query Transaction Status

This enables you to directly query the transaction status using the TransactionIDs

Test Endpoint:

https://api.sandbox.pesaway.com/api/v1/mobile-money/transaction-query/

# Request Parameters

Request Parameters Field Description Example
TransactionReference A transaction reference for the target transaction PHYD5AD5ASDF5

# Request Sample

curl --location --request GET 'https://api.sandbox.pesaway.com/api/v1/mobile-money/transaction-query/' \
--header 'X-Region: ke' \
--data-raw '{
    "TransactionReference": "PHYD5AD5ASDF5"
  }'

# Response Sample

{
  "Reference": "PHYD5AD5ASDF5",
  "PhoneNumber": "2547xx000xxx",
  "Receipt": "QTD5AD5ASDF5",
  "Amount": "5000",
  "Charge": "45",
  "ResultDesc": "Transaction processed successfully",
  "ResultCode": "0"
}

# Response Parameters

Response Parameters Field Type Description
Reference The PesaWay internal reference for the transaction
PhoneNumber The receiving phone number
Receipt MNO receipt
Amount Amount sent out in the transaction
Charge Amount charged to facilitate the transaction
ResultDesc A sentense describing whether the transaction filed or succeeded
ResultCode A code representation of the results .e.g. 0

← Bank Transfer →