Signin

API Keys and Credentials

Api keys and other credentials will be used for the merchant to connect Pesaswap services like REST API, card payment checkout pages and woocommerce plugins from several payment processors.

How to view API Keys and Credentials?

Description Screenshot
1.) Goto Profile and Click "API Keys and Credentials"
2.) You can now see "API Keys and Credentials". Note: Merchant can only view the credentials after required docs submission.

Account Balance

An API intended to show your actual payment processor balance. Note: typically the query might take up to 30 seconds before it can fully process the request and give back the response from mpesa. It is due to mpesa asynchronous approach. we never know exactly when they send us back the response. So the query will ping the backend and will check if the callback has been received, and then show it to the merchant.

Mpesa Account Balance Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
PartyA Paybill Number Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
How to connect into Pesaswap MPesa Account Balance API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/mpesa/account-balance

Production: https://www.pesaswap.com/api/mpesa/account-balance

Mpesa Account Balance
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'PartyA' => '',
'paybill_description' => '',
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Mpesa Account Balance Request Response - successful request

Name Description Sample Value
Mpesa balance Mpesa balance { "Result": { "ResultType": 0, "ResultCode": 0, "ResultDesc": "The service request is processed successfully.", "OriginatorConversationID": "29757-156200000-1", "ConversationID": "AG_20210621_000079a8af797ec69XXX", "TransactionID": "PFL0000000", "ResultParameters": { "ResultParameter": [ { "Key": "AccountBalance", "Value": "Working Account|KES|0.00|0.00|0.00|0.00&Utility Account|KES|17167162.00|17167162.00|0.00|0.00&Charges Paid Account|KES|0.00|0.00|0.00|0.00&Organization Settlement Account|KES|0.00|0.00|0.00|0.00" }, { "Key": "BOCompletedTime", "Value": 20210621142339 } ] }, "ReferenceData": { "ReferenceItem": { "Key": "QueueTimeoutURL", "Value": "https://internalapi.safaricom.co.ke/mpesa/abresults/v1/submit" } } } }


 

Mpesa Account Balance Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }
error Invalid PartyA { "requestId": "81477-15653648-1", "errorCode": "400.002.02", "errorMessage": "Bad Request - Invalid PartyA" }

Note:  To be discarded anytime sooner. We recommend for new users to use our latest API to benefit the more enhanced security feature. Lastest AIRTEL API here.

Airtel Collection Payment API

Steps on how to connect Airtel Collection Payment API
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys, click the user icon on upper right menu and select API Key
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • Please see sample code below and parameter's definition.
BASE URL
  • Sandbox: https://devpesaswap.azurewebsites.net/api/airtel-collection-payment

  • Production: https://www.pesaswap.com/api/airtel-collection-payment
Airtel Collection Payment API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'transaction_external_id' => '',
'msisdn' => '',
'amount' => '',
'country' => 'KE',
'currency' => 'KES'
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Airtel Collection Payment API Parameters Definition

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
transaction_external_id Ideally a GUID / UUID format. This will be used for future queries like knowing what's the actual status of your payment transaction. We have three(3) transaction statuses. Pending, Completed and Failed. Yes
msisdn Receiver's paybill. Yes
amount Amount. Yes
country Country code. Yes
currency Money currency code. Yes

Airtel Collection Payment API Success Response

Description Sample Value
You will receive a json format showing success result. {
"data": {
"transaction": {
"id": "UdYjGxLgDKwkyHpzkfSr",
"status": "Success."
}
},
"status": {
"code": "200",
"success": true,
"result_code": "ESB000010",
"message": "Success."
}
}

Airtel Collection Payment API Error Response

Description Sample Value
You will receive a json format showing error result. {
"status": {
"code": "500",
"success": false,
"result_code": "ESB000033",
"message": "Invalid msisdn. It should be of 9 digits only."
}
}

Airtel Collection Refund API

Steps on how to connect Airtel Collection Refund API
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys, click the user icon on upper right menu and select API Key
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • Please see sample code below and parameter's definition.
BASE URL
  • Sandbox: https://devpesaswap.azurewebsites.net/api/airtel-collection-refund

  • Production: https://www.pesaswap.com/api/airtel-collection-refund
Airtel Collection Refund API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'transaction_external_id' => '',
'original_transaction_external_id' => ''
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Airtel Collection Refund API Parameters Definition

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
transaction_external_id Ideally a GUID / UUID format. This will be used for future queries like knowing what's the actual status of your payment transaction. We have three(3) transaction statuses. Pending, Completed and Failed. Yes
original_transaction_external_id The original collection payment that you want to refund. Yes

Airtel Collection Refund API Success Response

Description Sample Value
You will receive a json format showing success result. {
"data": {
"transaction": {
"airtel_money_id": "24510493008",
"status": "SUCCESS"
}
},
"status": {
"code": "200",
"success": true,
"result_code": "ESB000010",
"message": "SUCCESS"
}
}

Airtel Collection Refund API Error Response

Description Sample Value
You will receive a json format showing error result. {
"status": {
"code": "500",
"success": false,
"result_code": "1132",
"message": "The Request ID is invalid/Already processed."
}
}

Airtel Collection Transaction Inquiry API

Steps on how to connect Airtel Collection Transaction Inquiry API
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys, click the user icon on upper right menu and select API Key
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • Please see sample code below and parameter's definition.
BASE URL
  • Sandbox: https://devpesaswap.azurewebsites.net/api/airtel-collection-transaction-inquiry

  • Production: https://www.pesaswap.com/api/airtel-collection-transaction-inquiry
Airtel Collection Transaction Inquiry API
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>'',
'transaction_external_id'=>''
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

Airtel Collection Transaction Inquiry API Parameters Definition

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
transaction_external_id The transaction_external_id of the original transaction you want to view. Yes

Airtel Collection Transaction Inquiry API Success Response

Description Sample Value
You will receive a json format showing success result. {
"data": {
"transaction": {
"airtel_money_id": "24510509168",
"id": "o3ZOkWCuvJBmCzNbLRcp",
"message": "Your transaction has been successfully processed",
"status": "TS"
}
},
"status": {
"code": "200",
"success": true,
"result_code": "ESB000010",
"message": "SUCCESS"
}
}

Airtel Collection Transaction Inquiry API Error Response

Description Sample Value
You will receive a json format showing error result. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Airtel Disbursement Payment API

Steps on how to connect Airtel Disbursement Payment API
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys, click the user icon on upper right menu and select API Key
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • Please see sample code below and parameter's definition.
BASE URL
  • Sandbox: https://devpesaswap.azurewebsites.net/api/airtel-disburse-payment

  • Production: https://www.pesaswap.com/api/airtel-disburse-payment
Airtel Disbursement Payment API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'transaction_external_id' => '',
'msisdn' => '',
'amount' => '',
'country' => 'KE',
'currency' => 'KES'
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Airtel Disbursement Payment API Parameters Definition

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
transaction_external_id Ideally a GUID / UUID format. This will be used for future queries like knowing what's the actual status of your payment transaction. We have three(3) transaction statuses. Pending, Completed and Failed. Yes
msisdn Receiver's paybill. Yes
amount Amount. Yes
country Country code. Yes
currency Money currency code. Yes

Airtel Disbursement Payment API Success Response

Description Sample Value
You will receive a json format showing success result. {
"data": {
"transaction": {
"reference_id": "24510509419",
"airtel_money_id": "disburs-G54PSUOEUS-94REsO5Yt9jscp97qSpN",
"id": "94REsO5Yt9jscp97qSpN"
}
},
"status": {
"code": "200",
"success": true,
"result_code": "ESB000010",
"message": "24XXXXXXXXX. Ksh 150 deposited to fname lastname 07XXXXXXXX on 18/08/21 at 01:36 PM. New float balance is Ksh 57,804."
}
}

Airtel Disbursement Payment API Error Response

Description Sample Value
You will receive a json format showing error result. {
"status": {
"code": "500",
"success": false,
"result_code": "0000900",
"message": "Invalid Msisdn Length. Msisdn Length should be 9"
}
}

Airtel Disbursement Refund API

Steps on how to connect Airtel Disbursement Refund API
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys, click the user icon on upper right menu and select API Key
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • Please see sample code below and parameter's definition.
BASE URL
  • Sandbox: https://devpesaswap.azurewebsites.net/api/airtel-disburse-refund

  • Production: https://www.pesaswap.com/api/airtel-disburse-refund
Airtel Disbursement Refund API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'transaction_external_id' => '',
'source_disburse_transaction_external_id' => ''
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Airtel Disbursement Refund API Parameters Definition

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
transaction_external_id Ideally a GUID / UUID format. This will be used for future queries like knowing what's the actual status of your payment transaction. We have three(3) transaction statuses. Pending, Completed and Failed. Yes
source_disburse_transaction_external_id The original disbursement payment that you want to refund. Yes

Airtel Disbursement Refund API Success Response

Description Sample Value
You will receive a json format showing success result. {
"data": {
"transaction": {
"airtel_money_id": "disburs-G54PSUOEUS-1jiXGaJr3APcomnhCKgB"
}
},
"status": {
"code": "200",
"success": true,
"result_code": "ESB000010",
"message": "Success"
}
}

Airtel Collection Refund API Error Response

Description Sample Value
You will receive a json format showing error result. {
"status": {
"code": "500",
"success": false,
"result_code": "0000900",
"message": "The Request ID is invalid/Already processed."
}
}

Airtel Disbursement Transaction Inquiry API

Steps on how to connect Airtel Disbursement Transaction Inquiry API
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys, click the user icon on upper right menu and select API Key
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • Please see sample code below and parameter's definition.
BASE URL
  • Sandbox: https://devpesaswap.azurewebsites.net/api/airtel-disburse-transaction-inquiry

  • Production: https://www.pesaswap.com/api/airtel-disburse-transaction-inquiry
Airtel Collection Transaction Inquiry API
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>'',
'transaction_external_id'=>''
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

Airtel Disbursement Transaction Inquiry API Parameters Definition

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
transaction_external_id The transaction_external_id of the original transaction you want to view. Yes

Airtel Disbursement Transaction Inquiry API Success Response

Description Sample Value
You will receive a json format showing success result. {
"data": {
"transaction": {
"id": "4SbPZrvhd60WM1Gk39Yq",
"message": "Success",
"status": "TS"
}
},
"status": {
"code": "200",
"success": true,
"result_code": "ESB000010",
"message": "SUCCESS"
}
}

Airtel Disbursement Transaction Inquiry API Error Response

Description Sample Value
You will receive a json format showing error result. {
"status": {
"code": "500",
"success": false,
"result_code": "0000900",
"message": "Internal server error"
}
}

Airtel API - Recommended

Header Tokenization API Call

Steps on how to generate header token.
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys and other credentials, click the user icon on upper right menu and select API Keys and Credentials
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • Please see sample code below and parameter's definition.

Header Tokenization Request Parameter - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/tokenization
Production: https://api.pesaswap.com/api/tokenization

Method: POST

Parameter Description Mandatory
ConsumerKey This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
ApiKey This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "ConsumerKey":"your-ConsumerKey",
    "ApiKey":"your-ApiKey"
}

Successful request

Description Sample Value
Success response {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzUyOTUxMSwiaXNzIjoiaHR0cHM6Ly9kZXZwZXNhc3dhcC1jc2hhcnAuYXp1cmV3ZWJzaXRlcy5uZXQvIiwiYXVkIjoiaHR0cHM6Ly9kZXZwZXNhc3dhcC1jc2hhcnAuYXp1cmV3ZWJzaXRlcy5uZXQvIn0.aDQLlboozcqWFiUsMF25HdWua3QDITDqS3VmZsyVQQA",
    "expiry": "Thu, 01 Dec 2022 15:05:11 UTC"
}
Token Expiration 1 Hour


 

Error Response

Description Sample Value
Unauthorized Http error 401

AIRTEL Collection Payment API Call

Steps on how to connect AIRTEL Collection Payment API.

AIRTEL Collection Payment API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/airtel-collection-payment
Production: https://api.pesaswap.com/api/airtel-collection-payment

Method: POST

Parameter Description Mandatory
MerchantIdentifier your-MerchantIdentifier Yes
TransactionExternalId TransactionExternalId Yes
Msisdn Airtel phonenumber. Yes
Amount 1 Yes
Country KE Yes
Currency KES Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "MerchantIdentifier":"MerchantIdentifier",
    "TransactionExternalId":"TransactionExternalId",
    "Msisdn":"123456789",
    "Amount": "1",
    "Country": "KE",
    "Currency": "KES"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "Success." }


 

Error Response

Description Sample Value
Error response { "error": "Duplicate transaction_external_id." }

AIRTEL Collection Refund API Call

Steps on how to connect AIRTEL Collection Refund API.

AIRTEL Collection Refund API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/airtel-collection-refund
Production: https://api.pesaswap.com/api/airtel-collection-refund

Method: POST

Parameter Description Mandatory
MerchantIdentifier your-MerchantIdentifier Yes
OriginalTransactionExternalId OriginalTransactionExternalId Yes
TransactionExternalId TransactionExternalId Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "MerchantIdentifier":"MerchantIdentifier",
    "OriginalTransactionExternalId":"OriginalTransactionExternalId",
    "TransactionExternalId":"TransactionExternalId"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "Success." }


 

Error Response

Description Sample Value
Error response { "error": "Duplicate transaction_external_id." }

AIRTEL Collection Transaction Inquiry API Call

Steps on how to connect AIRTEL Collection Transaction Inquiry API.

AIRTEL Collection Transaction Inquiry API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/airtel-collection-transaction-inquiry
Production: https://api.pesaswap.com/api/airtel-collection-transaction-inquiry

Method: GET

Parameter Description Mandatory
TransactionExternalId TransactionExternalId Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "TransactionExternalId":"TransactionExternalId"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "{\"data\":{\"transaction\":{\"airtel_money_id\":\"null\",\"id\":\"aE9U97Hbm7Gw4UWvL0tH\",\"message\":\"The Request ID is invalid/Already processed.\",\"status\":\"TF\"}},\"status\":{\"response_code\":\"DP00800001006\",\"code\":\"200\",\"success\":true,\"result_code\":\"ESB000010\",\"message\":\"SUCCESS\"}}" }


 

Error Response

Description Sample Value
Unauthorized Http error 401

AIRTEL Disbursement Payment API Call

Steps on how to connect AIRTEL Disbursement Payment API.

AIRTEL Disbursement Payment API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/airtel-disburse-payment
Production: https://api.pesaswap.com/api/airtel-disburse-payment

Method: POST

Parameter Description Mandatory
MerchantIdentifier your-MerchantIdentifier Yes
TransactionExternalId TransactionExternalId Yes
Msisdn Airtel phonenumber. Yes
Amount 1 Yes
Country KE Yes
Currency KES Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "MerchantIdentifier":"MerchantIdentifier",
    "TransactionExternalId":"TransactionExternalId",
    "Msisdn":"123456789",
    "Amount": "1",
    "Country": "KE",
    "Currency": "KES"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "24510993434. Ksh 1 deposited to Hellen kimanza 0751435103 on 18/03/22 at 02:28 PM. New float balance is Ksh 57,610." }


 

Error Response

Description Sample Value
Error response { "error": "Duplicate transaction_external_id." }

AIRTEL Disbursement Refund API Call

Steps on how to connect AIRTEL Disbursement Refund API.

AIRTEL Disbursement Refund API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/airtel-disburse-refund
Production: https://api.pesaswap.com/api/airtel-disburse-refund

Method: POST

Parameter Description Mandatory
MerchantIdentifier your-MerchantIdentifier Yes
OriginalTransactionExternalId OriginalTransactionExternalId Yes
TransactionExternalId TransactionExternalId Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "MerchantIdentifier":"MerchantIdentifier",
    "OriginalTransactionExternalId":"OriginalTransactionExternalId",
    "TransactionExternalId":"TransactionExternalId"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "Success." }


 

Error Response

Description Sample Value
Error response { "error": "Original transaction did not exist." }

AIRTEL Disbursement Transaction Inquiry API Call

Steps on how to connect AIRTEL Disbursement Transaction Inquiry API.

AIRTEL Disbursement Transaction Inquiry API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/airtel-disburse-disburse-inquiry
Production: https://api.pesaswap.com/api/airtel-disburse-transaction-inquiry

Method: GET

Parameter Description Mandatory
TransactionExternalId TransactionExternalId Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "TransactionExternalId":"TransactionExternalId"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "{\"data\":{\"transaction\":{\"id\":\"aF7ZmdcZfQVp40JlYjpW\",\"message\":\"The Request ID is invalid/Already processed.\",\"status\":\"TF\"}},\"status\":{\"response_code\":\"DP00900001000\",\"code\":\"200\",\"success\":true,\"result_code\":\"ESB000010\",\"message\":\"SUCCESS\"}}" }


 

Error Response

Description Sample Value
Unauthorized Http error 401

Azure Function API

An azure functions API's serves as a utility API's for the gateway.

Iveri Tokenization API

How to connect Pesaswap Iveri Tokenization API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Iveri Tokenization API is a specialized azure function API that will generate digital signature needed for queries.

Iveri Tokenization API Request Parameters

Method: POST

Parameter Description Mandatory
code This serves as a network credential which will only be found in azure function admin dashboard.

Yes
place it in the body { "url":"https://portal.host.iveri.com/api/transactions?applicationid=merchant-app-id", "password":"iveri password" } Yes
How to connect into Pesaswap Iveri Tokenization API?

You needed the API and Consumer Key.

BASE URL

Production: https://iveri-tokenization.azurewebsites.net/api/iveri-token-function?code={code}

Iveri Tokenization API
1
2
3
4
5
6
7
8
9
10
$url = BASE URL;
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $azure_function_endpoint); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array( 'url' => $ViewTransactionRequestEndpoint.$request_id, 'password' =>$ViewTransactionPassword );(
$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);

Iveri Tokenization API Response - successful request

Sample Value
20210401095145658:gJ52HsfRP8gkVvHJv0jLhaiSGkJMazWynSbTNBIYWNg=


 

Iveri Tokenization API Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Azure Function Upload File

How to connect Pesaswap Azure Function Upload API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Azure Function Upload API is an api to upload mpesa imported transaction record directly to azure blob folder needed for http trigger azure functions which import the record into sql database.

Azure Function Upload File API Request Parameters

Method: POST

Parameter Description Mandatory
code This serves as a network credential which will only be found in azure function admin dashboard.

Yes
file browse mpesa imported transaction Yes
How to connect into Azure Function Upload File API?

You needed the API and Consumer Key.

BASE URL

Production: https://uploadfiletoblobstorage.azurewebsites.net/api/upload-file?code={code}

Transaction Daily Figure
1
2
3
4
5
6
7
8
9
10
11
12
13
14
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'file' => 'browse mpesa imported excel record'
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Azure Function Upload File API Response - successful request

Sample Value
success


 

Azure Function Upload File API - Error Response

Name Description Sample Value
error An http error will be shown if azure function code is invalid. 401: Unauthorized

Pesaswap API Postman Collection

Note:  To be discarded anytime sooner. We recommend for new users to use our latest API to benefit the more enhanced security feature. Lastest Mpesa API here.

Download our RESTful API Collection here.

Mpesa Mobile Banking API

Steps on how to connect Mpesa Mobile Banking API
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys, click the user icon on upper right menu and select API Key
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • To view the paybill description:
      1. Click [Mobile Banking] sidebar menu
      2. Click [Settings]
      3. Click [eye] icon on Mpesa Settings list
      4. Look for [Paybill Description] field.
        • Note: Mpesa settings need to be created first before you can view the [Paybill Description].

    • Please see sample code below and parameter's definition.

C2B Version 2 Request Parameters

Method: POST

Parameter Description Mandatory
method c2b Yes
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
CommandID CustomerPayBillOnline or CustomerBuyGoodsOnline Yes
Msisdn Customer’s mobile number Yes
Amount Actual amount to be paid Yes
transaction_external_id A GUID / UUID format. This will be used for future queries like knowing what's the actual status of your payment transaction. We have three(3) transaction statuses. Pending, Completed and Failed. Yes
BillRefNumber Generate your own BillRefNumber for c2b transaction. Yes
customer_external_id Must be GUID/UUID. Though it is optional, we strongly suggest to include this on api call for you to monitor the payment from your specific customers. No
How to connect into Pesaswap Mobile Banking API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/mobile-payment/v2

Production: https://www.pesaswap.com/api/pesaswap/mobile-payment/v2

C2B / Paybill
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
15
16
 
17
18
19
20
21
22
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'method' => 'c2b',
'consumer_key' => '',
'api_key' => '',
'Amount' => '',
'CommandID' => '',
'Msisdn' => '',
'paybill_description' => '',
'transaction_external_id' => '',
'BillRefNumber' => '',
'customer_external_id' => ''
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

C2B Version 2 Request Response - successful request

Name Description Sample Value
ResponseDescription Success response { "ResponseDescription": "Success. Request accepted for processing" }


 

C2B Version 2 Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

C2B Validation Request Parameters

This api call will be used to reconcile the manual C2B payment using the mpesa portal directly. The process must be 1.) Customer will immediately use the C2B payment portal. if successful, customer will receive the confirmation code or mpesa transaction id together with other mpesa payment details 2.) Using the confirmation code or mpesa transaction id, customer should validate the payment to the merchant portal. Please refer to the api requirement below.

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
transaction_external_id Ideally a GUID / UUID format. This will be used for future queries like knowing what's the actual status of your payment transaction. We have three(3) transaction statuses. Pending, Completed and Failed. Yes
confirmation_code A.K.A mpesa transaction id Yes
amount Actual amount paid Yes
How to connect into Pesaswap C2B Validation API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/mobile-payment/validate-c2b

Production: https://www.pesaswap.com/api/mobile-payment/validate-c2b

C2B Validation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'transaction_external_id' => '',
'confirmation_code' => '',
'amount' => '',
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

C2B Validation Request Response - successful request

Name Description Sample Value
success Success response { "success": "Payment has been succeeded." }


 

C2B Validation Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }
error Mismatch amount. Higher than c2b amount. { "error": "Amount 222.00 did not match. Higher than C2B amount." }
error Mismatch amount. Lower than c2b amount. { "error": "Amount 1.00 did not match. Lower than C2B amount." }
error Transaction with transaction_external_id was already validated. { "error": "Transaction 123456789374 has been validated." }

C2B Validation Link Color Meaning

Note: Technically the transaction already completed in mpesa dashboard via manual c2b payment. The colors will determine if the customer executed validation via merchant api call.

Name Color Photo
Success Dodger blue
Pending Orange
Failed Red

C2B Validation Message

Note: Under method column, CLICK the 'C2B' link to view the validation message.

Name Photo
Validation Message

Lipa / Mpesa Express Version 2 Request Parameter

Method: POST

Parameter Description Mandatory
method op Yes
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
PhoneNumber Customer’s mobile number Yes
Amount Actual amount to be paid Yes
transaction_external_id A GUID / UUID format. This will be used for future queries like knowing what's the actual status of your payment transaction. We have three(3) transaction statuses. Pending, Completed and Failed. Yes
customer_external_id Must be GUID/UUID. Though it is optional, we strongly suggest to include this on api call for you to monitor the payment from your specific customers. No
code_type till for tillcode, leave blank for shortcode No
How to connect into Pesaswap Mobile Banking API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/mobile-payment/v2

Production: https://www.pesaswap.com/api/pesaswap/mobile-payment/v2

Lipa / Mpesa Express
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'method' => 'op',
'consumer_key' => '',
'api_key' => '',
'PhoneNumber' => '',
'Amount' => '',
'paybill_description' => '',
'transaction_external_id' => '',
'customer_external_id' => ''
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Lipa / Mpesa Express Version 2 Request Response - successful request

Name Description Sample Value
ResponseDescription Success response { "ResponseDescription": "Success. Request accepted for processing" }


 

Lipa / MPesa Express Version 2 Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

B2C Version 2 Request Parameters

Method: POST

Parameter Description Mandatory
method b2c Yes
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
CommandID Also known as transaction type. We have three options for b2c
1.)SalaryPayment
2.)BusinessPayment
3.)PromotionPayment
Yes
PartyB Receiver’s mobile number Yes
Amount Actual amount to be paid Yes
transaction_external_id A GUID / UUID format. This will be used for future queries like knowing what's the actual status of your payment transaction. We have three(3) transaction statuses. Pending, Completed and Failed. Yes
customer_external_id Must be GUID/UUID. Though it is optional, we strongly suggest to include this on api call for you to monitor the payment from your specific customers. No
How to connect into Pesaswap Mobile Banking API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/mobile-payment/v2

Production: https://www.pesaswap.com/api/pesaswap/mobile-payment/v2

B2C
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
15
 
16
17
18
19
20
21
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'method' => 'b2c',
'consumer_key' => '',
'api_key' => '',
'CommandID' => '',
'PartyB' => '',
'Amount' => '',
'paybill_description' => '',
'transaction_external_id' => '',
'customer_external_id' => ''
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

B2C Version 2 Request Response - successful request

Name Description Sample Value
ResponseDescription Success response { "ResponseDescription": "Success. Request accepted for processing" }


 

B2C Version 2 Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Reprocess B2C API

This API is intended to reprocess Failed B2C transactions particularly if the reason is due to Mpesa network issues such as timeout, busy server and other related matter. Note: this is only intended for the existing b2c failed transactions which parameters are considerably correct and only experiencing the issues mentioned above. Wrong recorded parameters like Invalid PartyB (Phone) is not included in the scope.

Reprocess B2C API Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
transaction_external_id Must be the existing transaction_external_id of your failed b2c transaction. Yes
How to connect into Pesaswap Reprocess B2C API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/reprocess-b2c

Production: https://www.pesaswap.com/api/reprocess-b2c

Reprocess B2C API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'transaction_external_id' => ''
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Reprocess B2C API Request Response - successful request

Name Description Sample Value
ResponseDescription Success response { "ResponseDescription": "Success. Request accepted for processing" }


 

Reprocess B2C API Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Reversal Request Parameters

Method: POST

Parameter Description Mandatory
method rp Yes
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
Amount Actual amount to refund Yes
ReceiverParty Organization receiving the transaction, Shortcode (6 digits) Yes
TransactionID Unique key generated after payment has been completed. Yes
transaction_external_id This will serve as the primary key for transaction's query. Pesaswap assumed that user's saved and inlcude this key after sending any of those mobile banking api payment request. Yes
How to connect into Pesaswap Mobile Banking API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/mobile-payment

Production: https://www.pesaswap.com/api/pesaswap/mobile-payment

Reversal
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
 
14
15
16
17
18
19
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'method' => 'rp',
'consumer_key' => '',
'api_key' => '',
'Amount' => '',
'ReceiverParty' => '',
'TransactionID' => '',
'paybill_description' => '',
'transaction_external_id' => ''
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Reversal Request Response - successful request

Name Description Sample Value
OriginatorConversationID An Originator Conversation ID from mpesa. 15772-2120045-1
ConversationID Conversation ID from mpesa. AG_20191011_00006c6617e36862f7b9
ResponseCode Response code from mpesa. IE. 0 means successful. 0
ResponseDescription Actual message from mpesa endpoint. Accept the service request successfully


 

Reversal Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }.


 

Reversal Error Response - mpesa exception

Name Description Sample Value
requestId From mpesa endpoint. 26967-2138090-1
errorCode From mpesa endpoint. 400.002.02
errorMessage Actual error message from mpesa endpoint. Bad Request - Invalid ReceiverParty

Mpesa Test Creds

Note: This credentials will only works in devsite or sandbox [https://devpesaswap.azurewebsites.net] endpoint.

Name Value
consumer_key rDBCp10qm0
api_key YEl40QSXo0M3N8G9pXKkuJo2U
paybill_description CC689940-EB4A-11E9-B56F-012AAE5B409B
PhoneNumber 254708374149

Mpesa API - Recommended

Header Tokenization API Call

Steps on how to generate header token.
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys and other credentials, click the user icon on upper right menu and select API Keys and Credentials
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • Please see sample code below and parameter's definition.

Header Tokenization Request Parameter - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/tokenization
Production: https://api.pesaswap.com/api/tokenization

Method: POST

Parameter Description Mandatory
ConsumerKey This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
ApiKey This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "ConsumerKey":"your-ConsumerKey",
    "ApiKey":"your-ApiKey"
}

Successful request

Description Sample Value
Success response {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzUyOTUxMSwiaXNzIjoiaHR0cHM6Ly9kZXZwZXNhc3dhcC1jc2hhcnAuYXp1cmV3ZWJzaXRlcy5uZXQvIiwiYXVkIjoiaHR0cHM6Ly9kZXZwZXNhc3dhcC1jc2hhcnAuYXp1cmV3ZWJzaXRlcy5uZXQvIn0.aDQLlboozcqWFiUsMF25HdWua3QDITDqS3VmZsyVQQA",
    "expiry": "Thu, 01 Dec 2022 15:05:11 UTC"
}
Token Expiration 1 Hour


 

Error Response

Description Sample Value
Unauthorized Http error 401

MPESA B2C API Call

Steps on how to connect MPESA B2C API.

MPESA B2C API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/mpesa-b2c
Production: https://api.pesaswap.com/api/mpesa-b2c

Method: POST

Parameter Description Mandatory
PaybillDescription your-PaybillDescription Yes
Amount Amount to payout. Yes
CommandId SalaryPayment Yes
PartyB Mpesa Receiver's phone Yes
ExternalId your-ExternalId Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "PaybillDescription":"PaybillDescription",
    "Amount":10,
    "CommandId":"SalaryPayment",
    "PartyB": "254722102170",
    "ExternalId": "ExternalId"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "Accept the service request successfully." }


 

Error Response

Description Sample Value
Error response { "error": "Duplicate transaction_external_id." }

MPESA C2B API Call

Steps on how to connect MPESA C2B API.

MPESA C2B API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/mpesa-c2b-billrefno
Production: https://api.pesaswap.com/api/mpesa-c2b-billrefno

Method: POST

Parameter Description Mandatory
PaybillDescription your-PaybillDescription Yes
Amount Amount to payin. Yes
CommandId CustomerPayBillOnline Yes
Msisdn Mpesa phone Yes
ExternalId your-ExternalId Yes
BillRefNumber your-BillRefNumber Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "PaybillDescription":"PaybillDescription",
    "Amount":10,
    "CommandId":"CustomerPayBillOnline",
    "Msisdn":"254708374140",
    "ExternalId": "ExternalId",
    "BillRefNumber": "BillRefNumber"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "Success. Request accepted for processing." }


 

Error Response

Description Sample Value
Error response { "error": "Duplicate ExternalId." }

MPESA LIPA API Call

Steps on how to connect MPESA LIPA API.

MPESA LIPA API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/mpesa-lipa
Production: https://api.pesaswap.com/api/mpesa-lipa

Method: POST

Parameter Description Mandatory
PaybillDescription your-PaybillDescription Yes
Amount Amount to payin. Yes
PhoneNumber Mpesa phone. Yes
ExternalId your-ExternalId Yes
Comment your-Comment or remarks Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "PaybillDescription":"PaybillDescription",
    "Amount":10,
    "PhoneNumber":"254708374140",
    "ExternalId": "ExternalId",
    "Comment": "Comment"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "Success. Request accepted for processing." }


 

Error Response

Description Sample Value
Error response { "error": "Duplicate ExternalId." }

MPESA REVERSAL API Call

Steps on how to connect MPESA REVERSAL API.

MPESA REVERSAL API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/mpesa-reversal
Production: https://api.pesaswap.com/api/mpesa-reversal

Method: POST

Parameter Description Mandatory
SourceExternalId The original transaction you want to reverse or refund Yes
ExternalId your-ExternalId Yes
ReceiverParty Paybill for shortcode, or store code for tillcode Yes
Amount Amount to reverse Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "SourceExternalId":"SourceExternalId",
    "ExternalId": "ExternalId",
    "ReceiverParty":"123456",
    "Amount":10 }

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "Accept the service request successfully." }


 

Error Response

Description Sample Value
Error response { "error": "Duplicate ExternalId." }

Header tokenization

Header Tokenization API Call

Steps on how to generate header token.
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys and other credentials, click the user icon on upper right menu and select API Keys and Credentials
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • Please see sample code below and parameter's definition.

Header Tokenization Request Parameter - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/tokenization
Production: https://api.pesaswap.com/api/tokenization

Method: POST

Parameter Description Mandatory
ConsumerKey This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
ApiKey This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "ConsumerKey":"your-ConsumerKey",
    "ApiKey":"your-ApiKey"
}

Successful request

Description Sample Value
Success response {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzUyOTUxMSwiaXNzIjoiaHR0cHM6Ly9kZXZwZXNhc3dhcC1jc2hhcnAuYXp1cmV3ZWJzaXRlcy5uZXQvIiwiYXVkIjoiaHR0cHM6Ly9kZXZwZXNhc3dhcC1jc2hhcnAuYXp1cmV3ZWJzaXRlcy5uZXQvIn0.aDQLlboozcqWFiUsMF25HdWua3QDITDqS3VmZsyVQQA",
    "expiry": "Thu, 01 Dec 2022 15:05:11 UTC"
}
Token Expiration 1 Hour


 

Error Response

Description Sample Value
Unauthorized Http error 401

Transaction API

The Pesaswap Transaction API provides the users what they need to know about their transactions especially the current status of their payment. Would it be Completed, Pending or Failed and other important details.

Completed status means the payment has been collected successfully from the customer. If it's still Pending status, the payment has been successfully processed on MPesa end but still waiting for the customer to execute the actual payment on their phone. Once it is Failed, means customer reject the payment call. For this case, you can send another api payment call to the customer.

The Pesaswap Transaction API has sandbox environment which you can request from Pesaswap Administrator for testing purposes. sandbox environment serves as a simulation of how API's work in production. Sandbox and Production keys are two different keys

How to connect into Pesaswap Transaction API?

You needed the API and Consumer Key.

Keys

Consumer and API Key, These are the keys to be used by merchants to connect into Pesaswap Transaction API. It should be included in the request body to determine if merchant has valid access to our api.

How to get the keys needed for Pesaswap Transaction API? Please contact us for more infos about the API.

Transaction Query Filter by "transaction_external_id" Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
transaction_external_id This will serve as the primary key for transaction's query. Pesaswap assumed that user's saved and inlcude this key after sending any of those mobile banking api payment request. Yes
How to connect into Pesaswap Mobile Banking API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/get-transaction-record

Production: https://www.pesaswap.com/api/get-transaction-record

Transaction Query Filter
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>'',
'transaction_external_id'=>''
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

Transaction Query Filter by "transaction_external_id" Request Response - successful request

Name Description Sample Value
transaction_external_id Unique ID generated by api users. 66f3d48093343538bca540a094c86e4e
transaction_id Transaction ID from mpesa endpoint. ABC56B5U0D, null
amount Transaction amount 10
status Status of the payment transaction. Pending, Failed, Completed
processor Payment processor mpesa, mastercard
method Payment method lipa / mpesa express, c2b, b2c
command_id Payment category CustomerPayBillOnline
customer Name of the customer. John Doe, John Delgado Doe, null


 

Transaction Query Filter by "transaction_external_id" request response - record not found

Name Description Sample Value
Record not found on pesaswap database. Record not found.


 

Transaction Query Filter by "transaction_external_id" Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Transaction Query Filter by "transaction_id" Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
transaction_id This is the mpesa transaction_id. NOTE: This is only available when the transaction status is Completed. If not Completed, this field is still empty. We recommend to use Transaction Query Filter by "transaction_external_id" above to check the status of the transaction. Yes
How to connect into Pesaswap Mobile Banking API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/get-transaction-record/filter-by-transaction-id

Production: https://www.pesaswap.com/api/get-transaction-record/filter-by-transaction-id

Transaction Query Filter
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>'',
'transaction_id'=>''
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

Transaction Query Filter by "transaction_id" Request Response - successful request

Name Description Sample Value
transaction_external_id Unique ID generated by api users. 66f3d48093343538bca540a094c86e4e
transaction_id Transaction ID from mpesa endpoint. ABC56B5U0D, null
transaction_type Transaction type. sales, refund(reversal)
amount Transaction amount 10
status Status of the payment transaction. Pending, Failed, Completed
processor Payment processor mpesa, mastercard
method Payment method lipa / mpesa express, c2b, b2c
command_id Payment category CustomerPayBillOnline
customer Name of the customer. John Doe, John Delgado Doe, null
phone Customer phone number. Used by credit card payment. 254720879123
address1 Main address of the customer. (Actual Address)
address2 Extended address of the customer. (Actual Extended Address)
city City address of the customer. (Actual City)
state_code State code address of the customer. (Actual state_code)
postal_code Postal code address of the customer. (Actual postal_code)
country_code Country code address of the customer. (Actual country_code)
credit_card_number_last_four Last four degit of credit card number. (valid credit card number)
credit_card_type Name of card company(bank). Mastercard, Discover, etc.
credit_card_key Security key. CVC, CVV.
routing Routing(bank). Valid Routing(bank).
rebill_routing Rebill routing(bank). Valid rebill routing(bank).
tax Applied transaction tax. Valid tax number.
order_id Order ID for credit card transaction. Unique varchar value as possible.
order_description Order description for credit card transaction. Order description.
shipping_firstname Shipping firstname for credit card transaction. Shipping firstname.
shipping_email Shipping email for credit card transaction. Shipping email.
shipping_phone Shipping phone for credit card transaction. Shipping phone.
shipping_phone Shipping phone for credit card transaction. Shipping phone.
shipping_address1 Shipping address for credit card transaction. Shipping address.
shipping_address2 Extended Shipping address for credit card transaction. Extended Shipping address.
shipping_city Shipping city for credit card transaction. Shipping city.
shipping_state_code Shipping state code for credit card transaction. Shipping state code.
shipping_postal_code Shipping postal code for credit card transaction. Shipping postal code.
shipping_country Shipping country for credit card transaction. Shipping country.
Initiator MPesa initiator, one of reversal parameter. Initiator.
InitiatorName MPesa initiator, one of B2C parameter. InitiatorName.
PartyA MPesa short code. Usually origin. PartyA.
PartyB MPesa short code. Usually receiver. PartyB.
Remarks MPesa remarks for transaction. Remarks.
Occasion MPesa occasion for transaction, similar to remarks. Occasion.
Msisdn MPesa Msisdn for transaction, usually phone number. Msisdn.
BillRefNumber Use as mpesa payment account number. LP331
ShortCode Mpesa shortcode. ShortCode(601400).
SenderIdentifier Mpesa SenderIdentifier(for B2B). SenderIdentifier
RecieverIdentifierType Mpesa RecieverIdentifierType(for B2B). RecieverIdentifierType
AccountReference Mpesa AccountReference. AccountReference
BusinessShortCode Mpesa BusinessShortCode. BusinessShortCode(another short code.)
Password Mpesa Password. User for access token. Password.
TransactionType TransactionType(N/A). TransactionType(N/A).
PhoneNumber MPesa phone number. MPesa phone number.
CallBackURL MPesa CallBackURL(N/A). MPesa CallBackURL(N/A).
TransactionDesc Mpesa transaction description. Mpesa transaction description.
mpesa_result_desc Mpesa response description. Mpesa response description..
paybill_description Unique GUID derived from mpesa settings. Unique GUID.
mpesa_customer Customer integrated from mpesa endpoint. Mpesa customer.
created_at Actual transaction date. Actual transaction date.


 

Transaction Query Filter by "transaction_id" request response - record not found

Name Description Sample Value
Record not found on pesaswap database. Record not found.


 

Transaction Query Filter by "transaction_id" Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Transaction Query All Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
start_date Transaction start date. Yes
end_date Transaction end date. Yes
skip Number of records to skip. Yes
take Number of records to display. Yes
How to connect into Pesaswap Mobile Banking API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/view-all-transactions-record

Production: https://www.pesaswap.com/api/view-all-transactions-record

Transaction Query All
1
2
3
4
 
5
6
7
8
9
10
11
12
13
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>''
'start_date'=>'mm/dd/yyyy'
'end_date'=>'mm/dd/yyyy'
'skip'=>'0'
'take'=>'100'
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

Transaction Query All Request Response - successful request

Name Description Sample Value
transaction_external_id Unique ID generated by api users. 66f3d48093343538bca540a094c86e4e
transaction_id Transaction ID from mpesa endpoint. ABC56B5U0D, null
transaction_type Transaction type. sales, refund(reversal)
amount Transaction amount 10
status Status of the payment transaction. Pending, Failed, Completed
processor Payment processor mpesa, mastercard
method Payment method lipa / mpesa express, c2b, b2c
command_id Payment category CustomerPayBillOnline
customer Name of the customer. John Doe, John Delgado Doe, null
phone Customer phone number. Used by credit card payment. 254720879123
address1 Main address of the customer. (Actual Address)
address2 Extended address of the customer. (Actual Extended Address)
city City address of the customer. (Actual City)
state_code State code address of the customer. (Actual state_code)
postal_code Postal code address of the customer. (Actual postal_code)
country_code Country code address of the customer. (Actual country_code)
credit_card_number_last_four Last four degit of credit card number. (valid credit card number)
credit_card_type Name of card company(bank). Mastercard, Discover, etc.
credit_card_key Security key. CVC, CVV.
routing Routing(bank). Valid Routing(bank).
rebill_routing Rebill routing(bank). Valid rebill routing(bank).
tax Applied transaction tax. Valid tax number.
order_id Order ID for credit card transaction. Unique varchar value as possible.
order_description Order description for credit card transaction. Order description.
shipping_firstname Shipping firstname for credit card transaction. Shipping firstname.
shipping_email Shipping email for credit card transaction. Shipping email.
shipping_phone Shipping phone for credit card transaction. Shipping phone.
shipping_phone Shipping phone for credit card transaction. Shipping phone.
shipping_address1 Shipping address for credit card transaction. Shipping address.
shipping_address2 Extended Shipping address for credit card transaction. Extended Shipping address.
shipping_city Shipping city for credit card transaction. Shipping city.
shipping_state_code Shipping state code for credit card transaction. Shipping state code.
shipping_postal_code Shipping postal code for credit card transaction. Shipping postal code.
shipping_country Shipping country for credit card transaction. Shipping country.
Initiator MPesa initiator, one of reversal parameter. Initiator.
InitiatorName MPesa initiator, one of B2C parameter. InitiatorName.
PartyA MPesa short code. Usually origin. PartyA.
PartyB MPesa short code. Usually receiver. PartyB.
Remarks MPesa remarks for transaction. Remarks.
Occasion MPesa occasion for transaction, similar to remarks. Occasion.
Msisdn MPesa Msisdn for transaction, usually phone number. Msisdn.
BillRefNumber Use as mpesa payment account number. LP331
ShortCode Mpesa shortcode. ShortCode(601400).
SenderIdentifier Mpesa SenderIdentifier(for B2B). SenderIdentifier
RecieverIdentifierType Mpesa RecieverIdentifierType(for B2B). RecieverIdentifierType
AccountReference Mpesa AccountReference. AccountReference
BusinessShortCode Mpesa BusinessShortCode. BusinessShortCode(another short code.)
Password Mpesa Password. User for access token. Password.
TransactionType TransactionType(N/A). TransactionType(N/A).
PhoneNumber MPesa phone number. MPesa phone number.
CallBackURL MPesa CallBackURL(N/A). MPesa CallBackURL(N/A).
TransactionDesc Mpesa transaction description. Mpesa transaction description.
mpesa_result_desc Mpesa response description. Mpesa response description..
paybill_description Unique GUID derived from mpesa settings. Unique GUID.
mpesa_customer Customer integrated from mpesa endpoint. Mpesa customer.
created_at Actual transaction date. Actual transaction date.


 

Transaction Query All request response - record not found

Name Description Sample Value
Record not found on pesaswap database. Record not found.


 

Transaction Query All Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

View Card Transaction Filter by RequestId (Iveri View Card Transaction)

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
request_id Card transaction request id. Yes
How to connect into Pesaswap View Card Transaction (Iveri View Card Transaction)?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/view/iveri-transaction

Production: https://www.pesaswap.com/api/view/iveri-transaction

Transaction Query Filter
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>'',
'request_id'=>''
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

View Card Transaction Filter by RequestId (Iveri View Card Transaction) - successful request

Json Response
{ "Version": "2.0", "Direction": "Response", "Transaction": { "DeviceSerialNumber": "", "MerchantTrace": "bd3f9680-6d99-11ea-9312-55871d88f5a3", "Amount": "1217500", "AuthorisationCode": "961091", "BudgetPeriod": "0", "Currency": "KES", "ExpiryDate": "072023", "MerchantReference": "bd3f9480-6d99-11ea-9fa3-b5482571cefb", "Terminal": "Default", "TransactionIndex": "27b18798-7104-46d2-899d-00b29fcf08dc", "MerchantUSN": "4000009004009", "Acquirer": "IMNaradaIMKenya", "AcquirerReference": "20200325:008406770626", "AcquirerDate": "20200324", "AcquirerTime": "083605", "DisplayAmount": "KSh 12,175.00", "BIN": "5", "PAN": "5173........5752", "PANMode": "Keyed,CVV", "ReconReference": "000212", "DeviceCycle": "", "ApplicationID": "6fb55598-97e1-4b6c-9b5d-2a7765e2709e", "Command": "Debit", "Mode": "Live", "RequestID": "f4f207f8-5e40-4000-a046-66f680470599", "Result": { "Status": "0", "Code": "0", "Description": "", "Source": "", "AppServer": "PRODGW2012APP1", "DBServer": "PRODGW2012DB2", "Gateway": "HOST" } } }

 

View Card Transaction Filter by RequestId (Iveri View Card Transaction) - Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }
Message Request Id is be incorrect. The request is invalid.
error Request Id is be incorrect. Please check the request_id.

View Card Transaction Filter by Application Id (Iveri View Card Transaction)

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
application_id Iveri Application Id. Yes
How to connect into Pesaswap View Card Transaction Filter By Application Id (Iveri View Card Transaction)?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/view/iveri-transaction/filter-by-application-id

Production: https://www.pesaswap.com/api/view/iveri-transaction/filter-by-application-id

Transaction Query Filter
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>'',
'application_id'=>''
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

View Card Transaction Filter by Application Id (Iveri View Card Transaction) - successful request

Json Array Response - Record for the last 7 days (2 sample records here).
[ { "Version": "2.0", "Direction": "Response", "Transaction": { "MerchantTrace": "46c8813c-09ad-4b48-bbf5-4a4b320d6654", "Amount": "10", "AuthorisationCode": "", "BudgetPeriod": "0", "CCNumber": "4054........9237", "Currency": "KES", "ExpiryDate": "072020", "MerchantReference": "41f1167c-9112-46ca-a69d-b0e856271f4y", "Terminal": "Default", "TransactionIndex": "d9226804-ad6d-4fd9-aa5d-a3ff26e804f2", "MerchantUSN": "4000009004009", "Acquirer": "IMNaradaIMKenya", "AcquirerReference": "20200402:009213688939", "AcquirerDate": "20200401", "AcquirerTime": "154100", "DisplayAmount": "KSh 0.10", "BIN": "4", "PAN": "4054........9237", "PANMode": "Keyed,CVV", "ReconReference": "000217", "ApplicationID": "6fb55598-97e1-4b6c-9b5d-2a7765e2709e", "Command": "Debit", "RequestID": "0c96eaac-38ac-460b-81bd-9c0d0b917d4d", "Result": { "Status": "-1", "Code": "-4", "Description": "Failed", "Source": "IMNaradaIMKenya", "AppServer": "PRODGW2012APP1", "DBServer": "PRODGW2012DB2", "Gateway": "HOST" } } }, { "Version": "2.0", "Direction": "Response", "Transaction": { "MerchantTrace": "46c8813c-09ad-4b48-bbf5-4a4b320d6654", "Amount": "10", "AuthorisationCode": "", "BudgetPeriod": "0", "CCNumber": "4054........9237", "Currency": "KES", "ExpiryDate": "072020", "MerchantReference": "41f1167c-9112-46ca-a69d-b0e856271f4y", "Terminal": "Default", "TransactionIndex": "d9226804-ad6d-4fd9-aa5d-a3ff26e804f2", "MerchantUSN": "4000009004009", "Acquirer": "IMNaradaIMKenya", "AcquirerReference": "20200402:009213688939", "AcquirerDate": "20200401", "AcquirerTime": "154142", "DisplayAmount": "KSh 0.10", "BIN": "4", "PAN": "4054........9237", "PANMode": "Keyed,CVV", "ReconReference": "000218", "ApplicationID": "6fb55598-97e1-4b6c-9b5d-2a7765e2709e", "Command": "Debit", "RequestID": "6164a6d9-07b1-4b3c-bad4-3b98f4fed047", "Result": { "Status": "-1", "Code": "-4", "Description": "Failed", "Source": "IMNaradaIMKenya", "AppServer": "PRODGW2012APP1", "DBServer": "PRODGW2012DB2", "Gateway": "HOST" } } } ]

 

View Card Transaction Filter by RequestId (Iveri View Card Transaction) - Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }
error Incorrect application id. Please check the application_id.

Reconciliation API Request Parameters

Other than automated throwing of callback response, we also have a manual trigger via api call called reconciliation api.

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
transaction_external_id This will serve as the primary key for transaction's query. Pesaswap assumed that user's saved and inlcude this key after sending any of those mobile banking api payment request. Yes
How to connect into Reconciliation API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/reconcile-transaction

Production: https://www.pesaswap.com/api/reconcile-transaction

Reconciliation API
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>'',
'transaction_external_id'=>''
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

Reconciliation API successful request

Name Description Sample Value
success Success response. { "success": "Callback has been sent successfully." }


 

Reconciliation API Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Customer API

Customer's played an important role in ecommerce especially in sales or payment transactions. For monitoring purposes most of the time companies wanted to record their customers too. That's the reason why we provided you a customer API call.

The Pesaswap Customer API has sandbox environment which you can request from Pesaswap Administrator for testing purposes. sandbox environment serves as a simulation of how API's work in production. Sandbox and Production keys are two different keys

How to connect into Pesaswap Customer API?

You needed the API and Consumer Key.

Keys

Consumer and API Key, These are the keys to be used by merchants to connect into Pesaswap Customer API. It should be included in the request body to determine if merchant has valid access to our api.

How to get the keys needed for Pesaswap Customer API? Please contact us for more infos about the API.

Create Customer Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
firstname Customer's first name Yes
lastname Customer's last name Yes
email must be an email Yes
phone valid mobile number Yes
address1 Customer's valid address No
address2 Customer's valid address, could be address extension No
state Country's state, must be state code No
country Customer's country, must be country code No
external_id Must be GUID/UUID. Note: API user must save this to their end. If not provided, pesaswap will autogerate and include this on the response if all fields has been filled-up properly. No
How to connect into Pesaswap Customer API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/create/customer

Production: https://www.pesaswap.com/api/pesaswap/create/customer

Create Customer
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
15
16
17
 
18
19
20
21
22
23
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'firstname' => '',
'lastname' => '',
'email' => '',
'phone' => '',
'address1' => '',
'address2' => '',
'state' => '',
'country' => '',
'external_id' => ''
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Create Customer Request Response - successful request

Name Description Sample Value
external_id External ID, a unique GUID. FC3CAC60-ACEC-11E9-B3E4-CF823C818EBC
firstname Customer firstname. firstname
lastname Customer lastname. lastname
email Customer email. Valid email
phone Customer phone. Valid phone.
address1 Customer address. Address.
address2 Customer extended address. Address.
country Customer country code. country code.


 

Create Customer Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Update Customer Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
firstname Customer's first name Yes
lastname Customer's last name Yes
email must be an email Yes
phone valid mobile number Yes
address1 Customer's valid address No
address2 Customer's valid address, could be address extension No
state Country's state, must be state code No
country Customer's country, must be country code No
external_id This will serve as the primary key in updating customer's info. Pesaswap assumed that user's saved this key after sending Create Customer API's request. Yes
How to connect into Pesaswap Customer API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/update/customer

Production: https://www.pesaswap.com/api/pesaswap/update/customer

Update Customer
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
15
16
17
 
18
19
20
21
22
23
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'firstname' => '',
'lastname' => '',
'email' => '',
'phone' => '',
'address1' => '',
'address2' => '',
'state' => '',
'country' => '',
'external_id' => ''
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Update Customer Request Response - successful request

Name Description Sample Value
external_id External ID, a unique GUID. FC3CAC60-ACEC-11E9-B3E4-CF823C818EBC
firstname Customer firstname. firstname
lastname Customer lastname. lastname
email Customer email. Valid email
phone Customer phone. Valid phone.
address1 Customer address. Address.
address2 Customer extended address. Address.
country Customer country code. country code.


 

Update Customer Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Customer Query Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
external_id This will serve as the primary key for customer's query. Pesaswap assumed that user's saved this key after sending Create Customer API's request. Yes
How to connect into Pesaswap Mobile Banking API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/query/customer

Production: https://www.pesaswap.com/api/pesaswap/query/customer

Customer query filter
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>'',
'external_id'=>''
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

Customer Query Filter Request Response - successful request

Name Description Sample Value
external_id External ID, a unique GUID. FC3CAC60-ACEC-11E9-B3E4-CF823C818EBC
firstname Customer firstname. firstname
lastname Customer lastname. lastname
email Customer email. Valid email
phone Customer phone. Valid phone.
address1 Customer address. Address.
address2 Customer extended address. Address.
country Customer country code. country code.


 

Customer Query Filter Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Payment Request

Also known as a request for payment, is a usual request made by a company, individual, or any business sector for approval of payment for goods or services. It is often used for purchases when an invoice is not provided.

If you needed a utility software that will send an invoice or payment request via email or phone number, Pesawap Payment Request API is the perfect choice for you. This tool is very easy to use. Fully powered RESTFul API that is compatible for WebApp, WebForms(Desktop) and even Mobile App. Payment method is user-friendly. 1.) Create a request via Pesaswap Payment Request API 2.) Customer or Payor will receive payment infos and a link to our Payment IFrame to their email or phone number. 3.) Using the link we sent, customer will now pay using Lipa na Mpesa Express , B2C / Paybill or even via Credit Card.

The Pesaswap Payment Request API has sandbox environment which you can request from Pesaswap Administrator for testing purposes. sandbox environment serves as a simulation of how API's work in production. Sandbox and Production keys are two different keys

How to connect into Pesaswap Payment Request API?

You needed the API and Consumer Key as well as the Paybill Description.

Keys

Consumer and API Key, These are the keys to be used by merchants to connect into Pesaswap Payment Request API. It should be included in the request body to determine if merchant has valid access to our api.

How to get the keys needed for Pesaswap Payment Request API? Please contact us for more infos about the API.

Send Payment Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
description Transaction description. IE. Payment for goods. Yes
range 1 - One time payment. Also known as instant payment method. Once triggered, payment request will be received instantly by the customer or payor through their email or phone number. Yes
billing_date Ideally transaction current date. format: mm/dd/yyyy. IE. 10/23/2019 Yes
last_billing_date Ideally transaction current date. format: mm/dd/yyyy. IE. 10/23/2019 Yes
external_id Customer external_id. This must be generated on api user's end and must be included on Pesaswap Create Customer API Call. Note: If this is provided, phone is no longer needed(exclude in the parameter). You can send request to multiple customers by using comma(,) as delimiter. IE. customer_external_id#1, customer_external_id#2. It means you are sending the payment request to two(2) different customer. No
phone_number Assuming you don't have customer's yet on Pesaswap End.You can still send Payment Request through phone numbers(Maximum of 9). Note: You must exclude the external_id to let the pesaswap api know that you will send a request to their phones. You can also send request to multiple phones by using comma(,) as delimiter. IE. 254708374148, 254708374149. It means you are sending the payment request to two(2) different phones. No
total_amount Amount to be paid. Yes
How to connect into Pesaswap Payment Request API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request

Production: https://www.pesaswap.com/api/payment/request

Multiple customer
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '1',
'external_id' => 'external_id#1,external_id#2',
'billing_date' => '10/23/2019',
'last_billing_date' => '10/23/2019',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);
Multiple phone number
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '1',
'phone_number' => '254708374148,254708374149',
'billing_date' => '10/23/2019',
'last_billing_date' => '10/23/2019',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Send Payment Request Response - successful request

Name Description Sample Value
success Multiple customer Payment Request has been created successfully to customer.
success Multiple phone Payment Request has been successfully sent to phone number.


 

Send Payment Request Error Response

Name Description Sample Value
error An error will be shown if parameter phone_number is empty for multiple phone api call. Phone number is required.
error An error will be shown if parameter external_id is not exist for multiple customer api call. external_id does not exist:750719F0-9364-11E9-B2DD-5399F21EC503s
error An error will be shown if parameter total_amount is not a whole number. Invalid total_amount. Please enter whole number.

Recurring Billing

An advance feature of payement request. Also known as automated or scheduled payment request. Instead of performing one time fee or one time payment for a subscription type business(IE. Daily, weekly, Monthly, Quarterly, Semi-Annually, Annually, Terms), We strongly advise the API users to use Pesaswap Recurring Billing API to avoid the hassle of creating a payment request over and over again with similar details. The Pesaswap Recurring Billing API will be responsible of sending a payment request to the customer's email or phone base on the range set by the api users.

The Pesaswap Recurring Billing API has sandbox environment which you can request from Pesaswap Administrator for testing purposes. sandbox environment serves as a simulation of how API's work in production. Sandbox and Production keys are two different keys

How to connect into Pesaswap Recurring Billing API?

You needed the API and Consumer Key.

Keys

Consumer and API Key, These are the keys to be used by merchants to connect into Pesaswap Recurring Billing API. It should be included in the request body to determine if merchant has valid access to our api.

How to get the keys needed for Pesaswap Recurring Billing API? Please contact us for more infos about the API.

Daily Fee Recurring Billing Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
description Transaction description. IE. Payment for goods. Yes
range 2 - Daily Fee. Yes
billing_date The first billing date. Scheduler started sending automated payment request on this date on a daily basis. NOTE: This must be beyond the current date. format: mm/dd/yyyy. IE. 10/24/2019 Yes
last_billing_date The last billing date. The sending of automated payment request will stop until this date base on range format: mm/dd/yyyy. IE. 10/25/2019 Yes
external_id Customer external_id. This must be generated on api user's end and must be included on Pesaswap Create Customer API Call. Note: If this is provided, phone is no longer needed(exclude in the parameter). You can send request to multiple customers by using comma(,) as delimiter. IE. customer_external_id#1, customer_external_id#2. It means you are sending the payment request to two(2) different customer. No
phone_number Assuming you don't have customer's yet on Pesaswap End.You can still send Payment Request through phone numbers(Maximum of 9). Note: You must exclude the external_id to let the pesaswap api know that you will send a request to their phones. You can also send request to multiple phones by using comma(,) as delimiter. IE. 254708374148, 254708374149. It means you are sending the payment request to two(2) different phones. No
total_amount In recurring billing, The total amount will be devided base on the number of scheduled payment or range. IE. If Daily Fee set on 10/24/2019 with last billing date of 10/25/2019(2 days) with the total amount of 60, therefore the daily billing amount is equal to 30. Yes
How to connect into Pesaswap Recurring Billing API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing

Production: https://www.pesaswap.com/api/payment/request/recurring/billing

Multiple customer
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '2',
'external_id' => 'external_id#1,external_id#2',
'billing_date' => '10/24/2019',
'last_billing_date' => '10/25/2019',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);
Multiple phone number
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '2',
'phone_number' => '254708374148,254708374149',
'billing_date' => '10/24/2019',
'last_billing_date' => '10/25/2019',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Payment Request Daily Fee Recurring Billing Response - successful request

Name Description Sample Value
success Multiple customer Payment Request has been created successfully to customer.
success Multiple phone Payment Request has been successfully sent to phone number.


 

Payment Request Daily Fee Recurring Billing Error Response

Name Description Sample Value
error An error will be shown if parameter phone_number is empty for multiple phone api call. Phone number is required.
error An error will be shown if parameter external_id is not exist for multiple customer api call. external_id does not exist:750719F0-9364-11E9-B2DD-5399F21EC503s
error An error will be shown if parameter total_amount is not a whole number. Invalid total_amount. Please enter whole number.
error An error will be shown if the billing_date is not beyond current date. First billing date must beyond the current date.
error An error will be shown if the last_billing_date is not beyond billing_date. Last billing date must beyond the first billing date.

Weekly Fee Recurring Billing Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
description Transaction description. IE. Payment for goods. Yes
range 3 - Weekly Fee. Yes
billing_date The first billing date. Scheduler started sending automated payment request on this date on a weekly basis. NOTE: This must be beyond the current date. format: mm/dd/yyyy. IE. 10/24/2019 Yes
last_billing_date The last billing date. The sending of automated payment request will stop until this date base on range format: mm/dd/yyyy. IE. 10/31/2019 Yes
external_id Customer external_id. This must be generated on api user's end and must be included on Pesaswap Create Customer API Call. Note: If this is provided, phone is no longer needed(exclude in the parameter). You can send request to multiple customers by using comma(,) as delimiter. IE. customer_external_id#1, customer_external_id#2. It means you are sending the payment request to two(2) different customer. No
phone_number Assuming you don't have customer's yet on Pesaswap End.You can still send Payment Request through phone numbers(Maximum of 9). Note: You must exclude the external_id to let the pesaswap api know that you will send a request to their phones. You can also send request to multiple phones by using comma(,) as delimiter. IE. 254708374148, 254708374149. It means you are sending the payment request to two(2) different phones. No
total_amount In recurring billing, The total amount will be devided base on the number of scheduled payment or range. IE. If Weekly Fee set on 10/24/2019 with last billing date of 10/31/2019(2 weeks) with the total amount of 60, therefore the weekly billing amount is equal to 30. Yes
How to connect into Pesaswap Recurring Billing API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing

Production: https://www.pesaswap.com/api/payment/request/recurring/billing

Multiple customer
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '3',
'external_id' => 'external_id#1,external_id#2',
'billing_date' => '10/24/2019',
'last_billing_date' => '11/31/2019',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);
Multiple phone number
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '3',
'phone_number' => '254708374148,254708374149',
'billing_date' => '10/24/2019',
'last_billing_date' => '10/31/2019',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Payment Request Weekly Fee Recurring Billing Response - successful request

Name Description Sample Value
success Multiple customer Payment Request has been created successfully to customer.
success Multiple phone Payment Request has been successfully sent to phone number.


 

Payment Request Weekly Fee Recurring Billing Error Response

Name Description Sample Value
error An error will be shown if parameter phone_number is empty for multiple phone api call. Phone number is required.
error An error will be shown if parameter external_id is not exist for multiple customer api call. external_id does not exist:750719F0-9364-11E9-B2DD-5399F21EC503s
error An error will be shown if parameter total_amount is not a whole number. Invalid total_amount. Please enter whole number.
error An error will be shown if the billing_date is not beyond current date. First billing date must beyond the current date.
error An error will be shown if the last_billing_date is not beyond billing_date. Last billing date must beyond the first billing date.

Monthly Fee Recurring Billing Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
description Transaction description. IE. Payment for goods. Yes
range 4 - Monthly Fee. Yes
billing_date The first billing date. Scheduler started sending automated payment request on this date on a weekly basis. NOTE: This must be beyond the current date. format: mm/dd/yyyy. IE. 10/24/2019 Yes
last_billing_date The last billing date. The sending of automated payment request will stop until this date base on range format: mm/dd/yyyy. IE. 11/24/2019 Yes
external_id Customer external_id. This must be generated on api user's end and must be included on Pesaswap Create Customer API Call. Note: If this is provided, phone is no longer needed(exclude in the parameter). You can send request to multiple customers by using comma(,) as delimiter. IE. customer_external_id#1, customer_external_id#2. It means you are sending the payment request to two(2) different customer. No
phone_number Assuming you don't have customer's yet on Pesaswap End.You can still send Payment Request through phone numbers(Maximum of 9). Note: You must exclude the external_id to let the pesaswap api know that you will send a request to their phones. You can also send request to multiple phones by using comma(,) as delimiter. IE. 254708374148, 254708374149. It means you are sending the payment request to two(2) different phones. No
total_amount In recurring billing, The total amount will be devided base on the number of scheduled payment or range. IE. If Monthly Fee set on 10/24/2019 with last billing date of 11/24/2019(2 months) with the total amount of 60, therefore the monthly billing amount is equal to 30. Yes
How to connect into Pesaswap Recurring Billing API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing

Production: https://www.pesaswap.com/api/payment/request/recurring/billing

Multiple customer
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '4',
'external_id' => 'external_id#1,external_id#2',
'billing_date' => '10/24/2019',
'last_billing_date' => '11/24/2019',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);
Multiple phone number
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '4',
'phone_number' => '254708374148,254708374149',
'billing_date' => '10/24/2019',
'last_billing_date' => '11/24/2019',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Payment Request Monthly Fee Recurring Billing Response - successful request

Name Description Sample Value
success Multiple customer Payment Request has been created successfully to customer.
success Multiple phone Payment Request has been successfully sent to phone number.


 

Payment Request Monthly Fee Recurring Billing Error Response

Name Description Sample Value
error An error will be shown if parameter phone_number is empty for multiple phone api call. Phone number is required.
error An error will be shown if parameter external_id is not exist for multiple customer api call. external_id does not exist:750719F0-9364-11E9-B2DD-5399F21EC503s
error An error will be shown if parameter total_amount is not a whole number. Invalid total_amount. Please enter whole number.
error An error will be shown if the billing_date is not beyond current date. First billing date must beyond the current date.
error An error will be shown if the last_billing_date is not beyond billing_date. Last billing date must beyond the first billing date.

Quarterly Fee Recurring Billing Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
description Transaction description. IE. Payment for goods. Yes
range 5 - Quarterly Fee (Every 3 months). Yes
billing_date The first billing date. Scheduler started sending automated payment request on this date on a quarterly basis. NOTE: This must be beyond the current date. format: mm/dd/yyyy. IE. 10/24/2019 Yes
last_billing_date The last billing date. The sending of automated payment request will stop until this date base on range format: mm/dd/yyyy. IE. 01/24/2020 Yes
external_id Customer external_id. This must be generated on api user's end and must be included on Pesaswap Create Customer API Call. Note: If this is provided, phone is no longer needed(exclude in the parameter). You can send request to multiple customers by using comma(,) as delimiter. IE. customer_external_id#1, customer_external_id#2. It means you are sending the payment request to two(2) different customer. No
phone_number Assuming you don't have customer's yet on Pesaswap End.You can still send Payment Request through phone numbers(Maximum of 9). Note: You must exclude the external_id to let the pesaswap api know that you will send a request to their phones. You can also send request to multiple phones by using comma(,) as delimiter. IE. 254708374148, 254708374149. It means you are sending the payment request to two(2) different phones. No
total_amount In recurring billing, The total amount will be devided base on the number of scheduled payment or range. IE. If Quarterly Fee set on 10/24/2019 with last billing date of 01/24/2020(2 quarters) with the total amount of 60, therefore the quarterly billing amount is equal to 30. Yes
How to connect into Pesaswap Recurring Billing API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing

Production: https://www.pesaswap.com/api/payment/request/recurring/billing

Multiple customer
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '5',
'external_id' => 'external_id#1,external_id#2',
'billing_date' => '10/24/2019',
'last_billing_date' => '01/24/2020',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);
Multiple phone number
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '5',
'phone_number' => '254708374148,254708374149',
'billing_date' => '10/24/2019',
'last_billing_date' => '01/24/2020',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Payment Request Quarterly Fee Recurring Billing Response - successful request

Name Description Sample Value
success Multiple customer Payment Request has been created successfully to customer.
success Multiple phone Payment Request has been successfully sent to phone number.


 

Payment Request Quarterly Fee Recurring Billing Error Response

Name Description Sample Value
error An error will be shown if parameter phone_number is empty for multiple phone api call. Phone number is required.
error An error will be shown if parameter external_id is not exist for multiple customer api call. external_id does not exist:750719F0-9364-11E9-B2DD-5399F21EC503s
error An error will be shown if parameter total_amount is not a whole number. Invalid total_amount. Please enter whole number.
error An error will be shown if the billing_date is not beyond current date. First billing date must beyond the current date.
error An error will be shown if the last_billing_date is not beyond billing_date. Last billing date must beyond the first billing date.

Semi-Annually Fee Recurring Billing Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
description Transaction description. IE. Payment for goods. Yes
range 6 - Semi-Annually Fee (Every 6 months). Yes
billing_date The first billing date. Scheduler started sending automated payment request on this date on a quarterly basis. NOTE: This must be beyond the current date. format: mm/dd/yyyy. IE. 10/24/2019 Yes
last_billing_date The last billing date. The sending of automated payment request will stop until this date base on range format: mm/dd/yyyy. IE. 01/24/2020 Yes
external_id Customer external_id. This must be generated on api user's end and must be included on Pesaswap Create Customer API Call. Note: If this is provided, phone is no longer needed(exclude in the parameter). You can send request to multiple customers by using comma(,) as delimiter. IE. customer_external_id#1, customer_external_id#2. It means you are sending the payment request to two(2) different customer. No
phone_number Assuming you don't have customer's yet on Pesaswap End.You can still send Payment Request through phone numbers(Maximum of 9). Note: You must exclude the external_id to let the pesaswap api know that you will send a request to their phones. You can also send request to multiple phones by using comma(,) as delimiter. IE. 254708374148, 254708374149. It means you are sending the payment request to two(2) different phones. No
total_amount In recurring billing, The total amount will be devided base on the number of scheduled payment or range. IE. If Semi-Annually Fee set on 10/24/2019 with last billing date of 04/24/2020(2 Semis) with the total amount of 60, therefore the Semi-Annually billing amount is equal to 30. Yes
How to connect into Pesaswap Recurring Billing API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing

Production: https://www.pesaswap.com/api/payment/request/recurring/billing

Multiple customer
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '6',
'external_id' => 'external_id#1,external_id#2',
'billing_date' => '10/24/2019',
'last_billing_date' => '04/24/2020',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);
Multiple phone number
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '6',
'phone_number' => '254708374148,254708374149',
'billing_date' => '10/24/2019',
'last_billing_date' => '04/24/2020',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Payment Request Semi-Annually Fee Recurring Billing Response - successful request

Name Description Sample Value
success Multiple customer Payment Request has been created successfully to customer.
success Multiple phone Payment Request has been successfully sent to phone number.


 

Payment Request Semi-Annually Fee Recurring Billing Error Response

Name Description Sample Value
error An error will be shown if parameter phone_number is empty for multiple phone api call. Phone number is required.
error An error will be shown if parameter external_id is not exist for multiple customer api call. external_id does not exist:750719F0-9364-11E9-B2DD-5399F21EC503s
error An error will be shown if parameter total_amount is not a whole number. Invalid total_amount. Please enter whole number.
error An error will be shown if the billing_date is not beyond current date. First billing date must beyond the current date.
error An error will be shown if the last_billing_date is not beyond billing_date. Last billing date must beyond the first billing date.

Annually Fee Recurring Billing Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
description Transaction description. IE. Payment for goods. Yes
range 7 - Annually Fee (Yearly). Yes
billing_date The first billing date. Scheduler started sending automated payment request on this date on annually basis. NOTE: This must be beyond the current date. format: mm/dd/yyyy. IE. 10/24/2019 Yes
last_billing_date The last billing date. The sending of automated payment request will stop until this date base on range format: mm/dd/yyyy. IE. 10/24/2020 Yes
external_id Customer external_id. This must be generated on api user's end and must be included on Pesaswap Create Customer API Call. Note: If this is provided, phone is no longer needed(exclude in the parameter). You can send request to multiple customers by using comma(,) as delimiter. IE. customer_external_id#1, customer_external_id#2. It means you are sending the payment request to two(2) different customer. No
phone_number Assuming you don't have customer's yet on Pesaswap End.You can still send Payment Request through phone numbers(Maximum of 9). Note: You must exclude the external_id to let the pesaswap api know that you will send a request to their phones. You can also send request to multiple phones by using comma(,) as delimiter. IE. 254708374148, 254708374149. It means you are sending the payment request to two(2) different phones. No
total_amount In recurring billing, The total amount will be devided base on the number of scheduled payment or range. IE. If the Annually Fee set on 10/24/2019 with last billing date of 10/24/2020(2 years) with the total amount of 60, therefore the Annually billing amount is equal to 30. Yes
How to connect into Pesaswap Recurring Billing API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing

Production: https://www.pesaswap.com/api/payment/request/recurring/billing

Multiple customer
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '7',
'external_id' => 'external_id#1,external_id#2',
'billing_date' => '10/24/2019',
'last_billing_date' => '10/24/2020',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);
Multiple phone number
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '7',
'phone_number' => '254708374148,254708374149',
'billing_date' => '10/24/2019',
'last_billing_date' => '10/24/2020',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Payment Request Annually Fee Recurring Billing Response - successful request

Name Description Sample Value
success Multiple customer Payment Request has been created successfully to customer.
success Multiple phone Payment Request has been successfully sent to phone number.


 

Payment Request Annually Fee Recurring Billing Error Response

Name Description Sample Value
error An error will be shown if parameter phone_number is empty for multiple phone api call. Phone number is required.
error An error will be shown if parameter external_id is not exist for multiple customer api call. external_id does not exist:750719F0-9364-11E9-B2DD-5399F21EC503s
error An error will be shown if parameter total_amount is not a whole number. Invalid total_amount. Please enter whole number.
error An error will be shown if the billing_date is not beyond current date. First billing date must beyond the current date.
error An error will be shown if the last_billing_date is not beyond billing_date. Last billing date must beyond the first billing date.

Terms Fee Recurring Billing Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
paybill_description Every api must have an admin settings. You can request this key from administrator or please contact us for more details.

Yes
description Transaction description. IE. Payment for goods. Yes
range 8 - Terms (Dynamic). Yes
billing_date The first billing date. Scheduler started sending automated payment request on this date on a quarterly basis. NOTE: This must be beyond the current date. format: mm/dd/yyyy. IE. 10/24/2019 Yes
last_billing_date The last billing date. The sending of automated payment request will stop until this date base on range format: mm/dd/yyyy. IE. 10/24/2019 Yes
external_id Customer external_id. This must be generated on api user's end and must be included on Pesaswap Create Customer API Call. Note: If this is provided, phone is no longer needed(exclude in the parameter). You can send request to multiple customers by using comma(,) as delimiter. IE. customer_external_id#1, customer_external_id#2. It means you are sending the payment request to two(2) different customer. No
phone_number Assuming you don't have customer's yet on Pesaswap End.You can still send Payment Request through phone numbers(Maximum of 9). Note: You must exclude the external_id to let the pesaswap api know that you will send a request to their phones. You can also send request to multiple phones by using comma(,) as delimiter. IE. 254708374148, 254708374149. It means you are sending the payment request to two(2) different phones. No
total_amount In terms fee recurring billing, ideally total amount will be the billing amount. IE. Usually terms billing_date is equal to last billing date. If the total amount is equal to 60, then the billing amount is also 60. Note: If you set the last billing date beyond the billing date, it will generate billing every single day. IE. Billing date is 10/24/2020 and Last Billing Date is 10/26/2020 therefore, it will send a payent request three times amounting to 60 each day. Yes
How to connect into Pesaswap Recurring Billing API?

You needed the API and Consumer Key as well as the Paybill Description.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing

Production: https://www.pesaswap.com/api/payment/request/recurring/billing

Multiple customer
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '8',
'external_id' => 'external_id#1,external_id#2',
'billing_date' => '01/24/2020',
'last_billing_date' => '01/24/2020',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);
Multiple phone number
1
2
3
4
 
 
5
6
7
8
9
10
11
12
13
14
 
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'paybill_description' => '',
'description' => '',
'range' => '8',
'phone_number' => '254708374148,254708374149',
'billing_date' => '01/24/2020',
'last_billing_date' => '01/24/2020',
'total_amount' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Payment Request Terms Fee Recurring Billing Response - successful request

Name Description Sample Value
success Multiple customer Payment Request has been created successfully to customer.
success Multiple phone Payment Request has been successfully sent to phone number.


 

Payment Request Terms Fee Recurring Billing Error Response

Name Description Sample Value
error An error will be shown if parameter phone_number is empty for multiple phone api call. Phone number is required.
error An error will be shown if parameter external_id is not exist for multiple customer api call. external_id does not exist:750719F0-9364-11E9-B2DD-5399F21EC503s
error An error will be shown if parameter total_amount is not a whole number. Invalid total_amount. Please enter whole number.
error An error will be shown if the billing_date is not beyond current date. First billing date must beyond the current date.
error An error will be shown if the last_billing_date is not beyond billing_date. Last billing date must beyond the first billing date.

Wallet API - Recommended

Header Tokenization API Call

Steps on how to generate header token.
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys and other credentials, click the user icon on upper right menu and select API Keys and Credentials
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • Please see sample code below and parameter's definition.

Header Tokenization Request Parameter - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/tokenization
Production: https://api.pesaswap.com/api/tokenization

Method: POST

Parameter Description Mandatory
ConsumerKey This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
ApiKey This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "ConsumerKey":"your-ConsumerKey",
    "ApiKey":"your-ApiKey"
}

Successful request

Description Sample Value
Success response {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzUyOTUxMSwiaXNzIjoiaHR0cHM6Ly9kZXZwZXNhc3dhcC1jc2hhcnAuYXp1cmV3ZWJzaXRlcy5uZXQvIiwiYXVkIjoiaHR0cHM6Ly9kZXZwZXNhc3dhcC1jc2hhcnAuYXp1cmV3ZWJzaXRlcy5uZXQvIn0.aDQLlboozcqWFiUsMF25HdWua3QDITDqS3VmZsyVQQA",
    "expiry": "Thu, 01 Dec 2022 15:05:11 UTC"
}
Token Expiration 1 Hour


 

Error Response

Description Sample Value
Unauthorized Http error 401

Airtel Collection Payment WALLET API

Steps on how to connect Airtel Collection Payment WALLET API.

Airtel Collection Payment WALLET API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/wallet/airtel-collection-payment
Production: https://api.pesaswap.com/api/wallet/airtel-collection-payment

Method: POST

Parameter Description Mandatory
MerchantIdentifier your-MerchantIdentifier Yes
TransactionExternalId your-TransactionExternalId Yes
Msisdn Airtel phone number Yes
Amount amount to be paid Yes
Country KE Yes
Currency KES Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "MerchantIdentifier":"MerchantIdentifier",
    "TransactionExternalId": "your-TransactionExternalId",
    "Msisdn":"789743304",
    "Amount":10,
    "Country": "KE",
    "Currency": "KES"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "Success." }


 

Error Response

Description Sample Value
Error response { "error": "Duplicate transaction_external_id." }

Airtel Disbursement Payment WALLET API

Steps on how to connect Airtel Disbursement Payment WALLET API.

Airtel Disbursement Payment WALLET API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/wallet/airtel-disburse-payment
Production: https://api.pesaswap.com/api/wallet/airtel-disburse-payment

Method: POST

Parameter Description Mandatory
MerchantIdentifier your-MerchantIdentifier Yes
TransactionExternalId your-TransactionExternalId Yes
Msisdn Airtel phone number Yes
Amount amount to be transferred. Yes
Country KE Yes
Currency KES Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "MerchantIdentifier":"MerchantIdentifier",
    "TransactionExternalId": "your-TransactionExternalId",
    "Msisdn":"789743304",
    "Amount":10,
    "Country": "KE",
    "Currency": "KES"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "24510993434. Ksh 1 deposited to Hellen kimanza 0751435103 on 18/03/22 at 02:28 PM. New float balance is Ksh 57,610." }


 

Error Response

Description Sample Value
Error response { "error": "Duplicate transaction_external_id." }

Balance Summary WALLET API

Steps on how to connect Balance Summary WALLET API.

Balance Summary WALLET API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/wallet/balance-summary
Production: https://api.pesaswap.com/api/wallet/balance-summary

Method: GET

Parameter Description Mandatory
MerchantIdentifier your-MerchantIdentifier Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "MerchantIdentifier":"MerchantIdentifier",
    "OriginalTransactionExternalId": "your-OriginalTransactionExternalId",
    "TransactionExternalId": "your-TransactionExternalId"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response {
"result": [
{
"sales": 10000,
"refund": 0,
"b2CReversal": 0,
"fundsTransfer": 2500,
"payout": 0,
"remainingBalance": 7500
}
]
}


 

Error Response

Description Sample Value
Error response { "result": "Invalid merchant identifier." }

Checkout Page With Cybersource Wallet

Another secured payment checkout page is via cybersource. Please see details below.

Steps on how to connect and setup the Card Payment Checkout Page With Cybersource
  1. Please login to production site or sandbox site portal as merchant.

  2. To view the merchant_identifier , click the user icon on upper right menu and select API Key and Credentials.
    • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the merchant_identifier.

  3. homePageUrl - Also known as landing or redirection page when you click the "Refresh Page" button after cybersource payment processes has been done. It just redirect to your ideal page.

  4. Create your own checkout page. How to do it? Please download the sample Iframe Code here. Replace the value of merchant_identifier and homePageUrl. You can design your own css for iframe as well.

Sample Checkout Page Via Cybersource Using an Iframe

 

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/cybersource/payment-info

Production: https://www.pesaswap.com/checkout/cybersource/payment-info

Parameter

Description Value Mandatory
merchant_identifier
  1. Please login to production site or sandbox site portal as merchant.
  2. To view the merchant_identifier , click the user icon on upper right menu and select API Key and Credentials.
    • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the merchant_identifier.
Yes
transaction_external_id Prefer GUID/UUID. Serves as a primary key for transaction and will be used for record integration, from Pesaswap to user’s end. Optional
customer_external_id Must be GUID/UUID. Though it is optional, we strongly suggest to include this on api call for you to monitor the payment from your specific customers. Optional
is_wallet 1 Yes for Pesaswap Wallet

Complete Iframe SRC Link

Description Value
Iframe sample link {{base_url}}?merchant_identifier=your-cybersource-identifier &&transaction_external_id=your-transaction-external-id &&customer_external_id=your-customer-external-id &&is_wallet=1

How to customize your logo?

How to change the checkout page logo into your own logo?
    1. Login as merchant to pesaswap.
    2. On sidebar menu, select Checkout Page .
    3. Select Upload Logo .
    4. Browse your logo and click Save.

Checkout Page With Iveri

Pesaswap offer a more secured and hassle free Credit Card payment called the checkout page. The user can just call the checkout page on their template through iframe, supply the required parameters and use it for card payment. It can cater both 3d secured enrolled and unenrolled card. Please see details below.

Steps on how to connect and setup the Card Payment Checkout Page With Iveri
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys, click the user icon on upper right menu and select API Key and Credentials.
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • To view the customer_external_id:
      1. Click [Customers] sidebar menu, use search engine if needed.
      2. Click [eye] icon on the list
      3. Look for [Exernal ID] field.

    • Generate token using tokenization api. Sample Code below.
    • Create an IFRAME or an HTML IFrame and supply the required parameter needed for the checkout page.
    • Please see sample code below and parameter's definition.

Pesaswap Tokenization

Tokenization is part of the checkout process. It is also serve as an identity of a merchant for a secured payment process.

Method: POST

BASE URL
  • Sandbox: https://devpesaswap.azurewebsites.net/api/generate-checkout-token

  • Production: https://www.pesaswap.com/api/generate-checkout-token
Pesaswap Tokenization
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => ''
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);
 

Pesaswap Tokenization Parameter

Description Value Mandatory
Consumer Key Merchant Consumer Key Yes
API Key Merchant API Key Yes

Pesaswap Tokenization Success Response

Description Value
The ‘token’ will be generated which will be used in one of the checkout page parameters. It will expire in 1 hour prior to the time of creation. { "token": "0f3b9af0-219a-11ea-992e-ff8147e8420a", "expiration": "yyyy-mm-dd hh:mm:ss" }

Pesaswap Tokenization Error Response

Description Value
An error will be raised if tokenization failes. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Checkout Page Using an Iframe

The checkout page could be grabbed and used using an iframe in your webapp or mobile page.

 

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/checkout/v1

Production: https://www.pesaswap.com/checkout/v1

Parameter

Description Value Mandatory
token Generated from api call (tokenization) Yes
currency Money currency Yes
amount Amount to be processes Yes
transaction_external_id Prefer GUID/UUID. Serves as a primary key for transaction and will be used for record integration, from Pesaswap to user’s end. Yes
customer_external_id An existing customer’s GUID/UUID saved on Pesaswap endpoint which serves as a primary key. No - for 3d secured enrolled card
Yes - for un-enrolled 3d secured card - required for fraud.net fraud manager.

Success Response

Description Value
Once payment has been succeeded, you will be redirected to success template. Payment has been succeeded.

Error Response

Description Value
You will be redirected to error template if something is not correct. Sample message: transaction_external_id already exist!, Missing PAN., etc.

Sample Html Code

Html Code
Download sample html iframe code.

Sample Checkout Page Via Iveri Using an Iframe

Checkout page

Complete Iframe SRC Link

Description Value
Iframe sample link {{base_url}}?token=your-token&& currency=KES&&amount=1&&transaction_external_id=your-transaction_external_id&&customer_external_id=your-customer_external_id&&is_wallet=1

How to customize your logo?

How to change the checkout page logo into your own logo?
    1. Login as merchant to pesaswap.
    2. On sidebar menu, select Checkout Page .
    3. Select Upload Logo .
    4. Browse your logo and click Save.

MPESA LIPA WALLET API

Steps on how to connect MPESA LIPA WALLET API.

MPESA LIPA WALLET API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/wallet/mpesa-lipa
Production: https://api.pesaswap.com/api/wallet/mpesa-lipa

Method: POST

Parameter Description Mandatory
MerchantIdentifier your-MerchantIdentifier Yes
TransactionExternalId your-TransactionExternalId Yes
Amount Amount to be paid. Yes
PhoneNumber Mpesa Receiver's phone Yes
Comment your-comment or remark Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "MerchantIdentifier":"MerchantIdentifier",
    "TransactionExternalId": "your-TransactionExternalId",
    "Amount":10,
    "PhoneNumber":"254123456789",
    "Comment": "your-Comment"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "Success. Request accepted for processing." }


 

Error Response

Description Sample Value
Error response { "error": "Duplicate transaction_external_id." }

MPESA B2C WALLET API

Steps on how to connect MPESA B2C WALLET API.

MPESA B2C WALLET API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/wallet/mpesa-b2c
Production: https://api.pesaswap.com/api/wallet/mpesa-b2c

Method: POST

Parameter Description Mandatory
MerchantIdentifier your-MerchantIdentifier Yes
TransactionExternalId your-TransactionExternalId Yes
Amount Amount to payout. Yes
CommandId ie. SalaryPayment Yes
PartyB receiver's mpesa phone number Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "MerchantIdentifier":"MerchantIdentifier",
    "TransactionExternalId": "your-TransactionExternalId",
    "Amount":10,
    "CommandId":"SalaryPayment",
    "PartyB": "254123456789"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "Accept the service request successfully." }


 

Error Response

Description Sample Value
Error response { "error": "Duplicate transaction_external_id." }

Refund WALLET API

Steps on how to connect Refund WALLET API.

Refund WALLET API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/wallet/refund
Production: https://api.pesaswap.com/api/wallet/refund

Method: POST

Parameter Description Mandatory
MerchantIdentifier your-MerchantIdentifier Yes
OriginalTransactionExternalId your-OriginalTransactionExternalId Yes
TransactionExternalId your-TransactionExternalId Yes

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "MerchantIdentifier":"MerchantIdentifier",
    "OriginalTransactionExternalId": "your-OriginalTransactionExternalId",
    "TransactionExternalId": "your-TransactionExternalId"
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response { "responseDescription": "Success. Request accepted for processing." }


 

Error Response

Description Sample Value
Error response { "error": "Duplicate transaction_external_id." }

Transactions List WALLET API

Steps on how to connect Transactions List WALLET API.

Transactions List WALLET API - JSON Body

BASE URL

Sandbox: https://devpesaswap-csharp.azurewebsites.net/api/wallet/transactions
Production: https://api.pesaswap.com/api/wallet/transactions

Method: GET

Parameter Description Mandatory
MerchantIdentifier your-MerchantIdentifier Yes
TransactionExternalId your-TransactionExternalId No
FromDate yyyy-mm-dd No
ToDate yyyy-mm-dd No
Status 1-Completed, 2-Failed, 3-Pending No
Skip 0 No
Take 10 No

Sample Body in JSON

Description Value
Body: JSON RAW Parameter {
    "MerchantIdentifier":"MerchantIdentifier",
    "TransactionExternalId": "your-TransactionExternalId",
    "FromDate": "2020-04-01",
    "ToDate": "2022-04-28",
    "Status": 2,
    "Skip": 0,
    "Take": 100
}

Sample Header

Description Value
Content-Type application/json
Authorization Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiUG93ZXJlZCBCeSBKV1QgVGVjaG5vbG9neSIsImV4cCI6MTY0NzE0ODU1NCwiaXNzIjoiaHR0cHM6Ly9hcGkucGVzYXN3YXAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLnBlc2Fzd2FwLmNvbS8ifQ.iNVIYmsGj10V5gjUPbEF7OPYfsodgp63DIiJaxEeyWY

Successful request

Description Sample Value
Success response {
"result": [
{ "transactionExternalId": "_test1232",
"transactionId": "N2N2FKQ9DRGVVUNARCOG",
"businessName": "top",
"type": "sales",
"status": "Failed",
"description": "The Request ID is invalid/Already processed.",
"amount": 1,
"currency": "KES",
"customer": "",
"mpesaCustomer": "",
"method": "airtel collection",
"phone": "789743304",
"dateCreated": "2022-04-21T17:06:07",
"eaDate": "2022-04-21T20:06:07" },
],
}


 

Error Response

Description Sample Value
Error response { "result": "Invalid merchant identifier." }

Woocommerce

Open-source software like woocommerce is very popular now a days where everyone can setup their own online store particularly wordpress users.

Pesaswap leverage the REST api as 1.) Pesaswap Collection (Mpesa, Airtel, MTN-Momo) and 2.) Pesaswap Card Checkout in a form of Woocommerce Plugin.

Pesaswap Woocommerce Plugin

Steps on how to use Woocommerce Plugin
    • Please login to production site or sandbox site portal as merchant.

    • To view the settings, click the user icon on upper right menu and select API Keys and Credentials

    • Please find the Woocommerce Plugin Settings located at LOWER part of the page page where you can download the plugin as well.
      1. Pesaswap Collection (Mpesa, Airtel, MTN-Momo) Woocommerce Plugin
      2. Pesaswap Card Checkout Woocommerce Plugin

Checkout Page With Iveri

Pesaswap offer a more secured and hassle free Credit Card payment called the checkout page. The user can just call the checkout page on their template through iframe, supply the required parameters and use it for card payment. It can cater both 3d secured enrolled and unenrolled card. Please see details below.

Steps on how to connect and setup the Card Payment Checkout Page With Iveri
    • Please login to production site or sandbox site portal as merchant.

    • To view the consumer and api keys, click the user icon on upper right menu and select API Key
      • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the api and consumer keys.

    • To view the customer_external_id:
      1. Click [Customers] sidebar menu, use search engine if needed.
      2. Click [eye] icon on the list
      3. Look for [Exernal ID] field.

    • Generate token using tokenization api. Sample Code below.
    • Create an IFRAME or an HTML IFrame and supply the required parameter needed for the checkout page.
    • Please see sample code below and parameter's definition.

Pesaswap Tokenization

Tokenization is part of the checkout process. It is also serve as an identity of a merchant for a secured payment process.

Method: POST

BASE URL
  • Sandbox: https://devpesaswap.azurewebsites.net/api/generate-checkout-token

  • Production: https://www.pesaswap.com/api/generate-checkout-token
Pesaswap Tokenization
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => ''
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);
 

Pesaswap Tokenization Parameter

Description Value Mandatory
Consumer Key Merchant Consumer Key Yes
API Key Merchant API Key Yes

Pesaswap Tokenization Success Response

Description Value
The ‘token’ will be generated which will be used in one of the checkout page parameters. It will expire in 1 hour prior to the time of creation. { "token": "0f3b9af0-219a-11ea-992e-ff8147e8420a", "expiration": "yyyy-mm-dd hh:mm:ss" }

Pesaswap Tokenization Error Response

Description Value
An error will be raised if tokenization failes. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Checkout Page Using an Iframe

The checkout page could be grabbed and used using an iframe in your webapp or mobile page.

 

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/three-d-secure/checkout/v2

Production: https://www.pesaswap.com/three-d-secure/checkout/v2

Parameter

Description Value Mandatory
token Generated from api call (tokenization) Yes
currency Money currency Yes
amount Amount to be processes Yes
transaction_external_id Prefer GUID/UUID. Serves as a primary key for transaction and will be used for record integration, from Pesaswap to user’s end. Yes
customer_external_id An existing customer’s GUID/UUID saved on Pesaswap endpoint which serves as a primary key. No - for 3d secured enrolled card
Yes - for un-enrolled 3d secured card - required for fraud.net fraud manager.

Success Response

Description Value
Once payment has been succeeded, you will be redirected to success template. Payment has been succeeded.

Error Response

Description Value
You will be redirected to error template if something is not correct. Sample message: transaction_external_id already exist!, Missing PAN., etc.

Sample Html Code

Html Code
Download sample html iframe code.

Sample Checkout Page Via Iveri Using an Iframe

Checkout page

How to customize your logo?

How to change the checkout page logo into your own logo?
    1. Login as merchant to pesaswap.
    2. On sidebar menu, select Checkout Page .
    3. Select Upload Logo .
    4. Browse your logo and click Save.

Checkout Page With Cybersource

Another secured payment checkout page is via cybersource. Please see details below.

Steps on how to connect and setup the Card Payment Checkout Page With Cybersource
  1. Please login to production site or sandbox site portal as merchant.

  2. To view the merchant_identifier , click the user icon on upper right menu and select API Key
    • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the merchant_identifier.

  3. homePageUrl - Also known as landing or redirection page when you click the "Refresh Page" button after cybersource payment processes has been done. It just redirect to your ideal page.

  4. Create your own checkout page. How to do it? Please download the sample Iframe Code here. Replace the value of merchant_identifier and homePageUrl. You can design your own css for iframe as well.

Sample Checkout Page Via Cybersource Using an Iframe

 

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/cybersource/payment-info

Production: https://www.pesaswap.com/checkout/cybersource/payment-info

Parameter

Description Value Mandatory
merchant_identifier
  1. Please login to production site or sandbox site portal as merchant.
  2. To view the merchant_identifier , click the user icon on upper right menu and select API Key
    • Note: Merchant needs to submit all the required documents first for KYC purposes before it can access the merchant_identifier.
Yes
transaction_external_id Prefer GUID/UUID. Serves as a primary key for transaction and will be used for record integration, from Pesaswap to user’s end. Optional
customer_external_id Must be GUID/UUID. Though it is optional, we strongly suggest to include this on api call for you to monitor the payment from your specific customers. Optional

Complete Iframe SRC Link

Description Value
Iframe sample link {{base_url}}?merchant_identifier=your-cybersource-identifier &&transaction_external_id=your-transaction-external-id &&customer_external_id=your-customer-external-id

How to customize your logo?

How to change the checkout page logo into your own logo?
    1. Login as merchant to pesaswap.
    2. On sidebar menu, select Checkout Page .
    3. Select Upload Logo .
    4. Browse your logo and click Save.

Regular Card Payment API

How to connect Pesaswap Regular Card Payment API?

You needed the Endpoint(Live or Sandbox) API Key and Consumer Key.

Pesaswap offered a REST API for regular card payment(un-enrolled 3d-secure card) with Fraud.Net banking API in the middle as a fraud manager.

Regular Card Payment API Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
currency Money currency. IE. KES Yes
amount Amount to be paid. Yes
expiry_date Card expiration date. format(mmyyyy). Yes
card_security_code Cvv or cvc. Yes
credit_card_number credit or debit card number. Yes
customer_external_id Must be GUID/UUID. API user is required to integrate their customer to pesaswap platform. Customer API docs here. Yes
transaction_external_id A GUID / UUID format. This will be used for future queries like knowing what's the actual status of your payment transaction. We have three(3) transaction statuses. Pending, Completed and Failed. Yes
environment test or live. Yes
How to connect into Pesaswap Regular Card Payment API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/regular/card-payment

Production: https://www.pesaswap.com/api/regular/card-payment

Card Payment
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => ' ',
'api_key' => ' ',
'currency' => 'KES',
'amount' => ' ',
'expiry_date' => 'mmyyyy',
'card_security_code' => ' ',
'credit_card_number' => ' ',
'customer_external_id' => ' ',
'transaction_external_id' => ' ',
'environment' => ' ' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Card Payment API Response - successful request

Name Description Sample Value
success Successful response. { "success": "Payment Successful." }


 

Card Payment API Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Test Cards

Card Number Card Type Expiry CVV Network
4000000000000002 Visa 01/**** 111 Regular
4242424242424242 MasterCard 01/**** 111 Regular
5200000000000007 MasterCard 01/**** 111 3d Secure
3520000000000922 JCB J/Secure 01/**** 111 3d Secure
340000000003961 American Express 01/**** 111 3d Secure
3005000000006246 Diners Club 01/**** 111 3d Secure
6011000000000004 Discover 01/**** 111 3d Secure

3d Secure Test OTP Creds

Credential
test123

Coupons

How to connect Pesaswap Coupon Payment API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Pesaswap offered a more secured and hassle free Credit Card payment called the checkout page. The user can just call the checkout page on their template through iframe, supply the required parameters and use it for card payment. It comes with two(2) versions or UI. For detailed infos, please download the checkout page manual.

Coupon Payment Query Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
identifier A unique identifier generated from pesaswap end. This will be the basis of which coupon will be used for the payment. Yes
amount Coupon amount. Should not be greater than the set amount on pesaswap end. Yes
customer_external_id Must be GUID/UUID. Though it is optional, we strongly suggest to include this on api call for you to monitor the payment from your specific customers. No
transaction_external_id A GUID / UUID format. This will be used for future queries like knowing what's the actual status of your payment transaction. We have three(3) transaction statuses. Pending, Completed and Failed. Yes
How to connect into Pesaswap Coupon Payment API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/coupon/payment

Production: https://www.pesaswap.com/api/coupon/payment

Coupon Payment
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'identifier' => '',
'amount' => '',
'customer_external_id' => '',
'transaction_external_id' => '' );

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Coupon Payment Request Response - successful request

Name Description Sample Value
success Successful response. { "success": "Coupon Payment Successful." }


 

Coupon Payment Filter Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }
error An error will be shown if Coupon does not exist. { "error": "Coupon does not exist, duration issue or in used." }
error An error will be shown if amount is invalid. { "error": "Request Amount:1500 is Greater than coupon amount:1000" }

Coupon Query Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
status If the status is provided, it will implement status filter. Note(1 - Active, 2 - Inactive, 3 -Used). No
identifier If the identifier is provided, it will implement identifier filter. No
How to connect into Pesaswap Coupon Query API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/coupon/query

Production: https://www.pesaswap.com/api/coupon/query

Coupon query filter
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
15
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>'',
'status'=>'1'
'identifier'=>'Nbg92'
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

Coupon Query Filter Request Response - successful request

Name Description Sample Value
Return the list of array/json objects [{ "merchant": "Top Merchant", "description": "Coupon one", "amount": "100", "period_start_date": "2020-01-27", "period_end_date": "2020-01-31", "guid": "42EA3140-40EB-11EA-8AC4-77A894670934", "identifier": null, "status": "Used" }]


 

Coupon Query Filter Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Interswitch Balance Inquiry Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
wallet_account Interswitch wallet account Yes
How to connect into Pesaswap-Interswitch Balance Inquiry API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/interswitch/balance-inquiry

Production: https://www.pesaswap.com/api/interswitch/balance-inquiry

Interswitch balance inquiry
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
15
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>'',
'wallet_account'=>''
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

Balance Inquiry Request Response - successful request

Name Description Sample Value
Return the list of array/json objects { "responseCode": "00", "responseMessage": "Approved or completed successfully", "availableBalance": 4988208.76, "ledgerBalance": 4988208.76 }


 

Balance Inquiry Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Transaction Inquiry Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
wallet_account Interswitch wallet account Yes
How to connect into Pesaswap-Interswitch transaction reference Inquiry API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/interswitch/transaction-inquiry

Production: https://www.pesaswap.com/api/interswitch/transaction-inquiry

Interswitch transaction inquiry
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
15
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>'',
'transaction_reference'=>''
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

Transaction Inquiry Request Response - successful request

Name Description Sample Value
Return the list of array/json objects { "responseCode": "00", "responseMessage": "Successful", "transaction": { "transactionType": "9005", "provider": "MPESA PAYBILL", "walletAccount": "8880000000000073", "beneficiaryAccount": "0722000000", "beneficiaryCard": "0722000000", "traceNumber": "243014", "rrn": "110457306441", "settleCurrency": "404", "settleAmount": "200.00", "providerID": "702", "beneficiaryDetails": "0722000000 - JOHN DOE", "responseCode": "00", "responseMessage": "Approved or completed successfully", "senderName": "Test Institution", "amount": "200.00", "reference": "142607387541012", "fee": "0.00", "transactionDate": "2021-04-14 18:48:26.21", "narration": "Payment", "providerReference": "MCQ4821JJJ", "issuerName": "SMART AC", "currency": "404", "transactionState": "1" } }


 

Transaction Inquiry Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }
error An error will be shown if parameter is not correct. { "responseCode": "25", "responseMessage": "Transaction(s) not found" }

Wallet details Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
wallet_account Interswitch wallet account Yes
How to connect into Pesaswap-Interswitch wallet details API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/interswitch/wallet-details

Production: https://www.pesaswap.com/api/interswitch/wallet-details

Interswitch wallet details
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
15
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>'',
'wallet_account'=>''
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

Wallet Details Request Response - successful request

Name Description Sample Value
Return the list of array/json objects { "responseCode": "00", "responseMessage": "Success", "wallet": { "product": "SMART_PT_CLS_PR", "customerNumber": "100000000136", "lastName": "SMART KADI TEST", "mobile": "254703053224", "email": "support.ke@interswitchgroup.com", "currency": "404", "walletAccount": "8880000000000073", "walletCard": "888000*0073", "walletCardSerno": 1410117 } }


 

Wallet details Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }
error An error will be shown if parameter is not correct. { "responseCode": "1", "responseMessage": "Entity not found" }

Wallet transaction Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
wallet_account Interswitch wallet account Yes
beneficiary_account Interswitch beneficiary account Yes
provider Interswitch provider's list Yes
sender_name Sender's name Yes
amount Amount to process Yes
narration A.K.A remarks Yes
How to connect into Pesaswap-Interswitch wallet transaction API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/interswitch/wallet-transaction

Production: https://www.pesaswap.com/api/interswitch/wallet-transaction

Interswitch wallet transaction
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'wallet_account' => '',
'sender_name' => '',
'beneficiary_account' => '',
'provider' => '',
'amount' => '',
'narration' => ''
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Wallet transaction Request Response - successful request

Name Description Sample Value
Return the list of array/json objects { "responseCode": "00", "responseMessage": "Approved or completed successfully", "rrn": "111058697832", "beneficiaryDetails": "0722000000 - JOHN DOE", "reference": "162076545386384", "fee": 0, "availableBalance": 4988122.52, "ledgerBalance": 4988122.52, "providerReference": "MCQ1128GSM" }


 

Wallet transaction Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Wallet provider Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. You can request this key from administrator or please contact us for more details.

Yes
api_key This serves as an api user password. You can request this key from administrator or please contact us for more details.

Yes
How to connect into Pesaswap-Interswitch wallet provider API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/interswitch/get-wallet-provider

Production: https://www.pesaswap.com/api/interswitch/get-wallet-provider

Interswitch wallet provider
1
2
3
4
5
 
6
7
8
9
10
11
12
13
14
$url = BASE URL;
$dataArray = array('consumer_key'=>'',
'api_key'=>''
);

$ch = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_URL, $getUrl);
curl_setopt($ch, CURLOPT_TIMEOUT, 80);
$response = curl_exec($ch);

Wallet provider Request Response - successful request

Name Description Sample Value
Return the list of array/json objects { "responseCode": "00", "responseMessage": "Successful", "providers": [ { "transactionType": "9002", "providerID": "901", "providerName": "KCB BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "902", "providerName": "STANDARD CHARTERED BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "903", "providerName": "BARCLAYS BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "905", "providerName": "BANK OF INDIA", "category": "BANK" }, { "transactionType": "9002", "providerID": "906", "providerName": "BANK OF BARODA", "category": "BANK" }, { "transactionType": "9002", "providerID": "907", "providerName": "NCBA", "category": "BANK" }, { "transactionType": "9002", "providerID": "910", "providerName": "PRIME BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "911", "providerName": "COOP BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "912", "providerName": "NATIONAL BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "914", "providerName": "ORIENTAL BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "916", "providerName": "CITI BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "917", "providerName": "HABIB BANK AG ZURICH", "category": "BANK" }, { "transactionType": "9002", "providerID": "918", "providerName": "MEB", "category": "BANK" }, { "transactionType": "9002", "providerID": "919", "providerName": "BANK OF AFRICA", "category": "BANK" }, { "transactionType": "9002", "providerID": "923", "providerName": "CONSOLIDATED BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "925", "providerName": "CREDIT BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "926", "providerName": "TRANSNATIONAL BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "930", "providerName": "CHASE BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "931", "providerName": "CFC STANBIC BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "935", "providerName": "ABC BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "942", "providerName": "GIRO BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "943", "providerName": "ECO BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "949", "providerName": "EQUATORIAL COMMERCIAL BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "950", "providerName": "PARAMOUNT BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "953", "providerName": "GTB BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "954", "providerName": "VICTORIA BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "959", "providerName": "DEVELOPMENT BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "960", "providerName": "FIDELITY BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "961", "providerName": "HOUSING FINANCE", "category": "BANK" }, { "transactionType": "9002", "providerID": "963", "providerName": "DTB BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "966", "providerName": "SIDIAN BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "968", "providerName": "EQUITY BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "970", "providerName": "FAMILY BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "972", "providerName": "GULF AFRICA BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "976", "providerName": "UBA BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "998", "providerName": "KWFT BANK", "category": "BANK" }, { "transactionType": "9002", "providerID": "999", "providerName": "POST BANK", "category": "BANK" }, { "transactionType": "9004", "providerID": "701", "providerName": "MPESA WALLET", "category": "MMO" }, { "transactionType": "9005", "providerID": "702", "providerName": "MPESA PAYBILL", "category": "MMO" }, { "transactionType": "9006", "providerID": "703", "providerName": "MPESA TILL", "category": "MMO" }, { "transactionType": "9004", "providerID": "700", "providerName": "TKASH WALLET", "category": "MMO" }, { "transactionType": "9004", "providerID": "704", "providerName": "AIRTEL WALLET", "category": "MMO" }, { "transactionType": "9000", "providerID": "888005", "providerName": "ISW WALLET", "category": "ISW" }, { "transactionType": "9002", "providerID": "975", "providerName": "DIB BANK", "category": "BANK" } ] }


 

Wallet provider Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Callback

Pesaswap could send to you the transaction records you needed the moment there will be changes of the transaction status from our end. We can relay it to you using your callback URL.

Callback Setup

For the merchant to receive the updated data from the gateway, they need to establish the requirement below.

  • Step 1: Your callback URL . Ideally a public page on your webApp where the gateway can throw the updated records if there is significant changes of the transaction status. IE. from Pending to Completed, or Failed.

  • Step 2: Please inform the Pesaswap Admin so that your callback URL will be added on the platform.

  • Step 3: How to get the record? The gateway will send to you this format. [your-callback-url]?data={json-string-formatted-data} So all you to do is to grab the values of [data] variable/parameter. Typical grabbing of data in a GET request method with the parameter name of [data].

  • Step 4: Decode the data from json-string-format to your ideal data format.
  • Step 5: Expected data format to receive below.
Name Sample Value
data {\"id\":636,\"business_name\":\"ABC Merchant\",\"transaction_external_id\":\"98470880-145c-11eb-993e-e9178dbfc53a\",\"transaction_id\":null,\"amount\":\"1\",\"status\":\"Failed\",\"mpesa_result_desc\":null,\"processor\":\"I&M Bank\",\"method\":\"CardPayment\",\"command_id\":null,\"customer\":\"Name Lastname\",\"send_to_callback_url\":\"https:\\/\\/devpesaswap.azurewebsites.net\\/mysite-callback.php\"}

Callback With Basic Header Auth - Expected Data to Receive

This will require consumer_key and api_key (base64 encoded) for the payload.

Method: Get

Header

Description Value
Content-Type application/json
Authorization "Basic " + "base64_encode(consumer_key:api_key)"

Details

Description Value
data {\"id\":636,\"business_name\":\"ABC Merchant\",\"transaction_external_id\":\"98470880-145c-11eb-993e-e9178dbfc53a\",\"transaction_id\":null,\"amount\":\"1\",\"status\":\"Failed\",\"mpesa_result_desc\":null,\"processor\":\"I&M Bank\",\"method\":\"CardPayment\",\"command_id\":null,\"customer\":\"Name Lastname\",\"send_to_callback_url\":\"https:\\/\\/devpesaswap.azurewebsites.net\\/mysite-callback.php\"}

Callback With Extended Header Auth - Expected Data to Receive

This will require consumer_key, api_key, external_id and amount (base64 encoded) for the payload. Note: amount format should be two decimal places IE. 1234.00 without commas.

Method: Get

Header

Description Value
Content-Type application/json
Authorization "Basic " + "base64_encode(consumer_key:api_key:external_id:amount)"

Details

Description Value
data {\"id\":636,\"business_name\":\"ABC Merchant\",\"transaction_external_id\":\"98470880-145c-11eb-993e-e9178dbfc53a\",\"transaction_id\":null,\"amount\":\"1\",\"status\":\"Failed\",\"mpesa_result_desc\":null,\"processor\":\"I&M Bank\",\"method\":\"CardPayment\",\"command_id\":null,\"customer\":\"Name Lastname\",\"send_to_callback_url\":\"https:\\/\\/devpesaswap.azurewebsites.net\\/mysite-callback.php\"}

Card Limit

A setting to determine if a merchant is allowed to use regular card payment api.

Merchant Description Value Tags
Assign specific Merchant regular_card_payment_limit_amount set limit amount iveri-regular-card-payment-limit-amount

Checkout Page

Checkout Page redirection url success page and error page can be customized by providing the custom url.

Merchant Description Value Tags
Merchant required success_page Merchant success page or site checkout-page
Merchant required error_page Merchant error page or site checkout-page

Coop Bank

Settings for coop bank.

Merchant Description Value Tags
Null(Leave it blank) token_endpoint https://openapi-sit.co-opbank.co.ke/token coop-bank
Null(Leave it blank) consumer_key valid consumer_key coop-bank
Null(Leave it blank) consumer_secret valid consumer_secret coop-bank
Null(Leave it blank) FundsTransfer_endpoint https://openapi-sit.co-opbank.co.ke/FundsTransfer/External/A2A/PesaLink/1.0.0et coop-bank
Null(Leave it blank) status_query_endpoint https://openapi-sit.co-opbank.co.ke/Enquiry/TransactionStatus/2.0.0 coop-bank
Null(Leave it blank) callback_url https://www.pesaswap.com/fundstransfer.php coop-bank
Null(Leave it blank) send_to_mpesa_endpoint https://openapi-sit.co-opbank.co.ke/FundsTransfer/External/A2M/Mpesa/1.0.0 coop-bank
Null(Leave it blank) account_balance_query_endpoint https://openapi-sit.co-opbank.co.ke/Enquiry/AccountBalance/1.0.0 coop-bank

Fraud.Net

Fraud.Net is the 3rd party fraud prevention api tool being used in card payment to prevent fraudulent transactions.

Merchant Description Value Tags
Null(Leave it blank) fraud_net_ecommerce_order_endpoint https://8007.api-production.fraud.net/v2/risk/order/ecommerce fraud-net
Null(Leave it blank) fraud_net_access_key access key fraud-net
Null(Leave it blank) fraud_net_secret_key secret key fraud-net
Null(Leave it blank) fraud_net_banking_endpoint https://8006.api-production.fraud.net/v2/risk/transaction/bank fraud-net
Null(Leave it blank) fraud_net_access_key_banking banking access key fraud-net
Null(Leave it blank) fraud_net_secret_key_banking banking secret key fraud-net

Fraud.Net Default Customer

Fraud.Net required customer's info. We can set the customer's default for the card payment api to use, NOTE: This is only for checkout page v2, currently the implementation is suspended.

Merchant Description Value Tags
Assign specific Merchant fraud_net_default_customer_external_id fraud.net customer external id fraud_net_default_customer_external_id

Flag SMS

Flag SMS is the SMS service provider. Currently can only cater Kenyan numbers.

Merchant Description Value Tags
Null(Leave it blank) flag_sms_api_passwd api password flag-sms
Null(Leave it blank) flag_sms_api_source source name flag-sms
Null(Leave it blank) flag_sms_api_user api user flag-sms
Null(Leave it blank) flag_sms_api_endpoint https://sms.flag42.com/api/index.php flag-sms
Null(Leave it blank) flag_sms_api_send_sms true or false (if true, sms will be sent, else, sms will NOT be sent) flag-sms

Iveri Live

A setting for iveri live payment.

Merchant Description Value Tags
Assign specific Merchant Version 2.0 iveri
Assign specific Merchant CertificateID Valid CertificateID iveri
Assign specific Merchant ProductType Enterprise iveri
Assign specific Merchant ProductVersion mPress iveri
Assign specific Merchant Direction Request iveri
Assign specific Merchant ApplicationID Valid ApplicationID iveri
Assign specific Merchant Command Debit iveri
Assign specific Merchant transaction_endpoint https://portal.host.iveri.com/api/transactions iveri
Assign specific Merchant TermUrl https://www.pesaswap.com/virtual-terminal/card-payment/three-d-secure iveri
Assign specific Merchant Mode Live iveri

Iveri Test

A setting for iveri sandbox or test environment.

Merchant Description Value Tags
Assign specific Merchant Version 2.0 iveri-test
Assign specific Merchant CertificateID Valid Sandbox CertificateID iveri-test
Assign specific Merchant ProductType Enterprise iveri-test
Assign specific Merchant ProductVersion mPress iveri-test
Assign specific Merchant Direction Request iveri-test
Assign specific Merchant ApplicationID Valid Sandbox ApplicationID iveri-test
Assign specific Merchant Command Debit iveri-test
Assign specific Merchant transaction_endpoint https://portal.host.iveri.com/api/transactions iveri-test
Assign specific Merchant TermUrl https://devpesaswap.azurewebsites.net/virtual-terminal/card-payment/three-d-secure iveri-test
Assign specific Merchant Mode Test iveri-test

Iveri Query

A setting for iveri query.

Merchant Description Value Tags
Assign specific Merchant ViewTransactionRequestEndpoint https://portal.host.iveri.com/api/transactions/ iveri-query
Assign specific Merchant Usergroup Valid Usergroup iveri-query
Assign specific Merchant UserName Valid user name iveri-query
Assign specific Merchant ViewTransactionPassword Valid password iveri-query
Assign specific Merchant azurefunctionendpoint https://iveri-tokenization.azurewebsites.net/api/iveri-token-function?code=e7rOMgmhFPLqPBVfw3u/Bajw1sWtp77N0LXm5h4OuNqrhOHqfvO4xw== iveri-query

Loyalty Card

Amount settings for loyalty card.

Merchant Description Value Tags
Assign specific Merchant loyalty_card_base_point Assign an Amount loyalty_card

Merchant Loan

Note: Applicable for all merchant but the amount of approval can be modified.

Merchant Description Value Tags
Null(Leave it blank) loan_basis_amount Set principal sales amount. IE. if set in 100. It means, The merchant can start processing their loan if the sales reaches to 100. merchant_loan
Null(Leave it blank) loan_amount_rate Set rate. Total percentage of loanable amount. IE. 75. It means, loanable amount is 75(base on 100 principal sales amount). merchant_loan
Null(Leave it blank) loan_amount_interest_rate Set interest rate. Simply the interest rate of the loanable amount. merchant_loan

Payout Notification

Payout email notification.

Merchant Description Value Tags
Null(Leave it blank) payout_notification Set the date to start notifying via email. IE. 2022-07-01 or in (yyyy-mm-dd) format payout-notification

Regular Card API Privilege

A setting to determine if a merchant is allowed to use regular card payment api.

Merchant Description Value Tags
Assign specific Merchant allow_regular_card_payment_api_call true or false (true if allowed, false if not) regular-card-payment

Sendgrid

Sendgrid email API using dynamic template.

Merchant Description Value Tags
Null(Leave it blank) mail_send_endpoint https://api.sendgrid.com/v3/mail/send sendgrid
Null(Leave it blank) api_key Sendgrid api_key sendgrid
Null(Leave it blank) from_email Catch all email sendgrid
Null(Leave it blank) access_code_template_id Access code valid template id sendgrid
Null(Leave it blank) reset_password_template_id Reset password valid template id sendgrid
Null(Leave it blank) public_registration_template_id Public registration valid template id sendgrid
Null(Leave it blank) contact_us_template_id Contact us valid template id sendgrid
Null(Leave it blank) payment_request_template_id Payment request valid template id sendgrid
Null(Leave it blank) payout_email_template_id Payout request valid template id sendgrid
Null(Leave it blank) payout_confirmation_template_id Payout confirmation valid template id sendgrid
Null(Leave it blank) withdrawal_request_template_id Withdrawal request valid template id sendgrid
Null(Leave it blank) credit_offer_template_id Credit offer valid template id sendgrid
Null(Leave it blank) member_access_code_template_id Member access code valid template id sendgrid
Null(Leave it blank) payment_code_template_id Pament code valid template id sendgrid
Null(Leave it blank) account_activation_template_id Account activation valid template id sendgrid

Service bus

Microservice who is responsible of processing api responses in the background.

Merchant Description Value Tags
Null(Leave it blank) service-bus-lipa Sevicebus-endpoint/publish/lipa service-bus
Null(Leave it blank) service-bus-c2b Sevicebus-endpoint/publish/c2b service-bus
Null(Leave it blank) service-bus-b2c Sevicebus-endpoint/publish/b2c service-bus
Null(Leave it blank) service-bus-producer-endpoint Sevicebus-endpoint/publish/producer service-bus

Session Timeout In Minutes

A setting to determine if how much time the gateway will auto-logout if the system is in idle.

Merchant Description Value Tags
Null(Leave it blank) session-timeout-in-minutes Set number of minutes session-timeout-in-minutes

Webhook

Callback sender setup.

Merchant Description Value Tags
Assign specific Merchant callback_url your-callback-url*mm/dd/yyyy webhook-callback
Assign specific Merchant header_auth true (if implement digital signature) or false(if no header auth) webhook-callback
If header_auth equal to 'true', add the value below.      
Assign specific Merchant consumer_key Consumer key webhook-callback
Assign specific Merchant api_key Api key webhook-callback

Analytics Migrate Transactions

How to connect Pesaswap Analytics Migrate Transactions API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Analytics table is the cloned version of transactions table. To avoid traffic in transactions table, a microservice will migrate all the records to analytics table for reporting purposes.

Analytics Migrate Transactions Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
How to connect into Pesaswap Analytics Migrate Transactions API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/analytics/migrate-transactions

Production: https://www.pesaswap.com/api/analytics/migrate-transactions

Analytics Migrate Transactions
1
2
3
4
5
6
7
8
9
10
11
$url = BASE URL;
$dataArray = array('consumer_key'=>'your-key','api_key'=>'your-key');
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);

Analytics Migrate Transactions Request Response - successful request

Sample Value
data inserted


 

Analytics Migrate Transactions Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Mpesa Customer Mapping

How to connect Pesaswap Mpesa Customer Mapping API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Mpesa Customer Mapping is the process of mapping out mpesa customer versus Pesaswap recorded customer. If the mpesa customer exist in Pesaswap end, it will map the existing transactions pointing to that specific customer base on their primary infos like phone.

Mpesa Customer Mapping Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
How to connect into Pesaswap Mpesa Customer Mapping API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/map-customer

Production: https://www.pesaswap.com/api/map-customer

Mpesa Customer Mapping
1
2
3
4
5
6
7
8
9
10
11
$url = BASE URL;
$dataArray = array('consumer_key'=>'your-key','api_key'=>'your-key');
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);

Mpesa Customer Mapping Request Response - successful request

Sample Value
Transaction Customer Mapping Done.


 

Mpesa Customer Mapping Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Integrate Mpesa Lipa and C2B Customer

How to connect Pesaswap Integrate Mpesa Customer API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Integrate Mpesa Customer API is responsible for downloading specifically for lipa and c2b mpesa transactions customers if not exist in Pesaswap endpoint.

Integrate Mpesa Customer for Lipa and C2B Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
How to connect into Pesaswap Integrate Mpesa Customer for Lipa and C2B API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/dashboard/mpesa/customer/integrate

Production: https://www.pesaswap.com/api/dashboard/mpesa/customer/integrate

Integrate Mpesa Customer for Lipa and C2B
1
2
3
4
5
6
7
8
9
10
11
$url = BASE URL;
$dataArray = array('consumer_key'=>'your-key','api_key'=>'your-key');
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);

Integrate Mpesa Customer for Lipa and C2B Request Response - successful request

Sample Value
Mpesa customer integrated Done - c2b and till code lipa.


 

Integrate Mpesa Customer for Lipa and C2B Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Integrate Mpesa B2C and Reversal Customer

How to connect Pesaswap Integrate Mpesa Customer API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Integrate Mpesa Customer API is responsible for downloading specifically b2c and reversal mpesa transactions customers if not exist in Pesaswap endpoint.

Integrate Mpesa Customer for B2C and Reversal Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
How to connect into Pesaswap Integrate Mpesa Customer for B2C and Reversal API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/dashboard/mpesa/customer/integrate-b2c-reversal

Production: https://www.pesaswap.com/api/dashboard/mpesa/customer/integrate-b2c-reversal

Integrate Mpesa Customer for B2C and Reversal
1
2
3
4
5
6
7
8
9
10
11
$url = BASE URL;
$dataArray = array('consumer_key'=>'your-key','api_key'=>'your-key');
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);

Integrate Mpesa Customer for B2C and Reversal Response - successful request

Sample Value
Mpesa customer integrated Done - execute_update_mpesa_customer_reversal_b2c.


 

Integrate Mpesa Customer for B2C and Reversal Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Integrate Mpesa Transaction

How to connect Pesaswap Integrate Mpesa Transaction API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Integrate Mpesa Transaction API is responsible for downloading mpesa payments transactions if not done in Pesaswap endpoint. IE. Manual C2B payment which is done on mpesa endpoint.

Integrate Mpesa Transaction Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
How to connect into Pesaswap Integrate Mpesa Transaction API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/integrate/mpesa/transaction

Production: https://www.pesaswap.com/api/integrate/mpesa/transaction

Integrate Mpesa Transaction
1
2
3
4
5
6
7
8
9
10
11
$url = BASE URL;
$dataArray = array('consumer_key'=>'your-key','api_key'=>'your-key');
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);

Integrate Mpesa Transaction Response - successful request

Sample Value
Mpesa transaction integrated.


 

Integrate Mpesa Transaction Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Payout Notification

How to connect Pesaswap Payout Notification API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Payout Notification API is responsible for sending email notifications for completed payouts.

Payout Notification Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
How to connect into Pesaswap Payout Notification API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/payout/notification

Production: https://www.pesaswap.com/api/payout/notification

Payout Notification
1
2
3
4
5
6
7
8
9
10
11
$url = BASE URL;
$dataArray = array('consumer_key'=>'your-key','api_key'=>'your-key');
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);

Payout Notification Response - successful request

Sample Value
Payout notification done.


 

Payout Notification Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Payout Scheduler

How to connect Pesaswap Payout Scheduler API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Payout Scheduler is responsible in sending payout notifications for existing recurring payouts.

Payout Scheduler Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
How to connect into Pesaswap Payout Scheduler API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/payout/scheduler

Production: https://www.pesaswap.com/api/payout/scheduler

Payout Scheduler
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Payout Scheduler Response - successful request

Sample Value
{ "Response": "Payout scheduler run successfully" }


 

Payout Scheduler Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Procees Fees

How to connect Pesaswap Procees Fees API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Procees Fees is responsible for merchant payin, payout and even processor fees computation base on fees settings.

Procees Fees Request Parameters

Method: POST

Parameter Description Mandatory
take This serves as records limit to minimize the use of RAM.

Yes
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
How to connect into Pesaswap Procees Fees API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/process/transaction-fees

Production: https://www.pesaswap.com/api/process/transaction-fees

Procees Fees
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'take' => '',
'consumer_key' => '',
'api_key' => '',
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);

Procees Fees Response - successful request

Sample Value
fees has been processed.


 

Procees Fees Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Payment Request Scheduler

How to connect Pesaswap Payment Request Scheduler API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Payment Request Scheduler API is responsible for sending email notifications for recurring payment.

Payment Request Scheduler Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
How to connect into Pesaswap Payment Request Scheduler API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/payment/scheduler

Production: https://www.pesaswap.com/api/payment/scheduler

Payment Request Scheduler
1
2
3
4
5
6
7
8
9
10
11
12
$url = BASE URL;
$dataArray = array('consumer_key'=>'your-key','api_key'=>'your-key');
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Payment Request Scheduler Response - successful request

Sample Value
{ "Response": "Scheduler run successfully" }


 

Payment Request Scheduler Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Webhook Callback

How to connect Pesaswap Webhook Callback API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Webhook Callback API is responsible for sending asynchronous response through merchant's callback url's.

Webhook Callback Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
How to connect into Pesaswap Webhook Callback API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/webhook-callback

Production: https://www.pesaswap.com/api/webhook-callback

Webhook Callback
1
2
3
4
5
6
7
8
9
10
11
12
$url = BASE URL;
$dataArray = array('consumer_key'=>'your-key','api_key'=>'your-key');
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Webhook Callback Response - successful request

Sample Value
{ "response": "webhook sent." }


 

Webhook Callback Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Send Access Code - AI

How to connect Pesaswap Send Access Code API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Send Access Code is a utility api designed for AI on Pesaswap Chatbot specifically for account balance. When a merchant wants to inquire their paybill balance, they will be prompted for an access code. This API is responsible of sending code to merchant's email in the background.

Send Access Code Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
paybill_number Merchant's mpesa paybill or till code.

Yes
How to connect into Pesaswap Send Access Code API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/account/balance/access-code

Production: https://www.pesaswap.com/api/account/balance/access-code

Send Access Code
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'paybill_number' => '',
'consumer_key' => '',
'api_key' => '',
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);

Send Access Code Response - successful request

Sample Value
{ "success": "success" }


 

Send Access Code Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Account Balance - AI

How to connect Pesaswap Account Balance API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Account Balance is a utility api designed for AI on Pesaswap Chatbot specifically for viewing current mpesa account balance.

Account Balance Request Parameters

Method: GET

Parameter Description Mandatory
access code An access code send to merchant's email

Yes
How to connect into Pesaswap Account Balance API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/account/balance/record/{access-code}

Production: https://www.pesaswap.com/api/account/balance/record/{access_code}

Account Balance
1
2
3
4
5
6
7
8
9
10
11
12
$url = BASE URL;
$dataArray = null;
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);

Account Balance Response - successful request

Sample Value
{ 'id' : 1, 'paybill_number': 123456, 'working' : 1000, 'utility' :, 'charges : 1000, 'organization' : 'organization' }


 

Account Balance Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Base 64 Code Generator

How to connect Pesaswap Base 64 Code Generator API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Base 64 Code Generator is a utility. This code is commonly used in generating access tokens.

Base 64 Code Generator Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
username username.

Yes
password password.

Yes
How to connect into Pesaswap Base 64 Code Generator API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/Base64Generator

Production: https://www.pesaswap.com/api/Base64Generator

Base 64 Code Generator
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'username' => '',
'password' => '',
'consumer_key' => '',
'api_key' => '',
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);

Base 64 Code Generator Response - successful request

Sample Value
bFg5T0NCUEwyWENKUE9hc2FzVFpCYXNhczpjZTg1ZTlhOS1jM2FzYXNiNC00NWE5LWI2MjMtZDVjNzI2ZmIxNGE3YXM=


 

Base 64 Code Generator Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Clear Analytics

How to connect Pesaswap Clear Analytics API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Clear Analytics is simply clearing the analytics table and ready for new migration again.

Clear Analytics Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
How to connect into Pesaswap Clear Analytics API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/clear/analytics

Production: https://www.pesaswap.com/api/clear/analytics

Clear Analytics
1
2
3
4
5
6
7
8
9
10
11
$url = BASE URL;
$dataArray = array('consumer_key'=>'your-key','api_key'=>'your-key');
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);

Clear Analytics Request Response - successful request

Sample Value
Record cleared.


 

Clear Analytics Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Credit Offer Computation

How to connect Pesaswap Credit Offer Computation API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Credit Offer Computation API is responsible of merchant's loan computation. The API will compute loanable amount base on the current settings.

Credit Offer Computation Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
How to connect into Pesaswap Credit Offer Computation API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/compute/credit/offer

Production: https://www.pesaswap.com/api/compute/credit/offer

Credit Offer Computation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Credit Offer Computation Response - successful request

Sample Value
{ "success": "Loan computation successfully ran." }


 

Credit Offer Computation Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Merchant Analytics View

How to connect Pesaswap Merchant Analytics View API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Merchant Analytics View API is the responsible for viewing analytics record filtered by merchant.

Merchant Analytics View Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username.

Yes
api_key This serves as an api user password.

Yes
skip Number of records to skip.

Yes
take Number of records to view.

Yes
How to connect into Pesaswap Merchant Analytics View API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/analytics/view-all-transactions-record

Production: https://www.pesaswap.com/api/analytics/view-all-transactions-record

Merchant Analytics View
1
2
3
4
5
6
7
8
9
10
11
$url = BASE URL;
$dataArray = array('consumer_key'=>'your-key','api_key'=>'your-key','skip'=>'valid-number','take'=>'valid-number');
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);

Merchant Analytics View Request Response - successful request

Sample Value
List of records in json format.


 

Merchant Analytics View Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Master-Admin Analytics View

How to connect Pesaswap Master-Admin Analytics View API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Master-Admin Analytics View is responsible viewing analytics record for all merchant.

Master-Admin Analytics View Request Parameters

Method: GET

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
skip Number of records to skip.

Yes
take Number of records to view.

Yes
How to connect into Pesaswap Master-Admin Analytics View API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/analytics/master-admin/view-all-transactions-record

Production: https://www.pesaswap.com/api/analytics/master-admin/view-all-transactions-records

Master-Admin Analytics View
1
2
3
4
5
6
7
8
9
10
11
$url = BASE URL;
$dataArray = array('consumer_key'=>'your-key','api_key'=>'your-key','skip'=>'valid-number','take'=>'valid-number');
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);

Master-Admin Analytics View Request Response - successful request

Sample Value
List of records in json format.


 

Master-Admin Analytics View Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

View Mpesa Missing Transaction

How to connect Mpesa Missing Transaction API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Missing Transaction API is a utility api that compares the sql recorded transaction and imported mpesa excel file. It will show what is missing in sql, but available in excel file, and vice versa.

Mpesa Missing Transaction Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
start_date Gateway Start Date - must be matched in excel starting date Yes
end_date Gateway End Date - must be matched in excel starting date Yes
case 1 = found in excel, not in gateway, 2 = found in gateway, not in excel Yes
file browse mpesa excel file Yes
type sales, payout, funds transfer Note: must match to excel file Yes
mid merchant primary key Yes
How to connect into Mpesa Missing Transaction API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/mpesa-missing-transaction

Production: https://www.pesaswap.com/api/mpesa-missing-transaction

Mpesa Missing Transaction
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'start_date' => 'mm/dd/yyyy',
'end_date' => 'mm/dd/yyyy',
'case' => '1',
'file' => 'excelfile.xlsx',
'type' => 'sales',
'mid' => '123456',
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Mpesa Missing Transaction Response - successful request

Description Sample Value
It will show an array of mpesa missing transaction ids [
"PD8212345",
"PD84PD821",
"PD2121287"
]


 

Mpesa Missing Transaction Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Transaction Daily Figure

How to connect Transaction Daily Figure API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Transaction Daily Figure is the utility api that shows the daily and total amount whithin the specific date range.

Transaction Daily Request Parameters

Method: POST

Parameter Description Mandatory
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
start_date Gateway Start Date - must be matched in excel starting date Yes
end_date Gateway End Date - must be matched in excel starting date Yes
type sales, payout, funds transfer , etc. Yes
mid merchant primary key Yes
How to connect into Transaction Daily Figure API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/transactions-daily-figures

Production: https://www.pesaswap.com/api/transactions-daily-figures

Transaction Daily Figure
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
$url = BASE URL;
$curl_init();
curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));

$curl_post_data = array(
'consumer_key' => '',
'api_key' => '',
'start_date' => 'mm/dd/yyyy',
'end_date' => 'mm/dd/yyyy',
'type' => 'sales',
'mid' => '123456'
);

$data_string = json_encode($curl_post_data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
$curl_response = curl_exec($curl);
$response = json_decode($curl_response,true);

Transaction Daily Figure Response - successful request

Description Sample Value
It will show a json formatted amount of transactions base on specific date range. {
"total amount": 6500,
"daily amount": [
{
"amount": 1000,
"day": "2021-06-01"
},
{
"amount": 2000,
"day": "2021-06-02"
},
{
"amount": 3500,
"day": "2021-06-03"
}
]
}


 

Transaction Daily Figure Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }

Transaction Figure

How to connect Pesaswap Transaction Figure API?

You needed the Endpoint(Live or Sandbox), API Key, Consumer Key.

Transaction Figure is the utility api that double check the transaction details like total amount, status, and even the count.

Transaction Figure Request Parameters

Method: GET

Parameter Description Mandatory
merchant_id Merchant's primary key.

Yes
consumer_key This serves as an api username. Note: Only master-admin keys will work.

Yes
api_key This serves as an api user password. Note: Only master-admin keys will work.

Yes
processor_id Processor's primary key. Yes
transaction_type IE. sales, payout, refund Yes
timezone EAT or UTC Yes
period_start_date start date of transaction. Yes
period_end_date end date of transaction. Yes
status 1-completed, 2-failed, 3-pending, 4-duplicated Yes
How to connect into Pesaswap Transaction Figure API?

You needed the API and Consumer Key.

BASE URL

Sandbox: https://devpesaswap.azurewebsites.net/api/transaction/figures

Production: https://www.pesaswap.com/api/transaction/figures

Transaction Figure
1
2
3
4
5
6
7
8
9
10
11
12
13
$url = BASE URL;
$dataArray = array('merchant_id'=>'', 'consumer_key'=>'your-key', 'api_key'=>'your-key', 'processor_id'=>'', 'transaction_type'=>'', 'timezone'=>'', 'period_start_date'=>'mm/dd/yyyy', 'period_end_date'=>'mm/dd/yyyy', 'status'=>'');
$curl = curl_init();
$data = http_build_query($dataArray);
$getUrl = $url."?".$data;
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_URL, $getUrl);
curl_setopt($curl, CURLOPT_TIMEOUT, 80);
$curl_response = curl_exec($curl);

Transaction Figure Request Response - successful request

Sample Value
[ { "merchant": "Merchant Name", "processor": "mpesa", "total": 1000000, "status": "Completed", "transaction_count": 1000 } ]


 

Transaction Figure Error Response

Name Description Sample Value
error An error will be shown if parameter is not correct. { "error": "Invalid Credentials. Please Check your consumer_key and api_key." }