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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/mpesa/account-balance
Production: https://www.pesaswap.com/api/mpesa/account-balance
$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
- 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.
- Sandbox: https://devpesaswap.azurewebsites.net/api/airtel-collection-payment
- Production: https://www.pesaswap.com/api/airtel-collection-payment
$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
- 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.
- Sandbox: https://devpesaswap.azurewebsites.net/api/airtel-collection-refund
- Production: https://www.pesaswap.com/api/airtel-collection-refund
$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
- 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.
- Sandbox: https://devpesaswap.azurewebsites.net/api/airtel-collection-transaction-inquiry
- Production: https://www.pesaswap.com/api/airtel-collection-transaction-inquiry
$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
- 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.
- Sandbox: https://devpesaswap.azurewebsites.net/api/airtel-disburse-payment
- Production: https://www.pesaswap.com/api/airtel-disburse-payment
$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
- 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.
- Sandbox: https://devpesaswap.azurewebsites.net/api/airtel-disburse-refund
- Production: https://www.pesaswap.com/api/airtel-disburse-refund
$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
- 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.
- Sandbox: https://devpesaswap.azurewebsites.net/api/airtel-disburse-transaction-inquiry
- Production: https://www.pesaswap.com/api/airtel-disburse-transaction-inquiry
$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
- 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
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
AIRTEL Collection Payment API - JSON Body
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
AIRTEL Collection Refund API - JSON Body
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
AIRTEL Collection Transaction Inquiry API - JSON Body
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
AIRTEL Disbursement Payment API - JSON Body
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
AIRTEL Disbursement Refund API - JSON Body
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
AIRTEL Disbursement Transaction Inquiry API - JSON Body
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
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 |
You needed the API and Consumer Key.
Production: https://iveri-tokenization.azurewebsites.net/api/iveri-token-function?code={code}
$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
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 |
You needed the API and Consumer Key.
Production: https://uploadfiletoblobstorage.azurewebsites.net/api/upload-file?code={code}
$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
- 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:
- Click [Mobile Banking] sidebar menu
- Click [Settings]
- Click [eye] icon on Mpesa Settings list
- 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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/mobile-payment/v2
Production: https://www.pesaswap.com/api/pesaswap/mobile-payment/v2
$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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/mobile-payment/validate-c2b
Production: https://www.pesaswap.com/api/mobile-payment/validate-c2b
$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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/mobile-payment/v2
Production: https://www.pesaswap.com/api/pesaswap/mobile-payment/v2
$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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/mobile-payment/v2
Production: https://www.pesaswap.com/api/pesaswap/mobile-payment/v2
$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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/reprocess-b2c
Production: https://www.pesaswap.com/api/reprocess-b2c
$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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/mobile-payment
Production: https://www.pesaswap.com/api/pesaswap/mobile-payment
$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
- 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
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
MPESA B2C API - JSON Body
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
MPESA C2B API - JSON Body
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
MPESA LIPA API - JSON Body
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
MPESA REVERSAL API - JSON Body
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
- 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
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
You needed the API and Consumer Key.
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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/get-transaction-record
Production: https://www.pesaswap.com/api/get-transaction-record
$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 |
You needed the API and Consumer Key.
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
$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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/view-all-transactions-record
Production: https://www.pesaswap.com/api/view-all-transactions-record
$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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/view/iveri-transaction
Production: https://www.pesaswap.com/api/view/iveri-transaction
$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 |
You needed the API and Consumer Key.
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
$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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/reconcile-transaction
Production: https://www.pesaswap.com/api/reconcile-transaction
$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
You needed the API and Consumer Key.
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 |
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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/create/customer
Production: https://www.pesaswap.com/api/pesaswap/create/customer
$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 |
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 |
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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/update/customer
Production: https://www.pesaswap.com/api/pesaswap/update/customer
$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 |
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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/pesaswap/query/customer
Production: https://www.pesaswap.com/api/pesaswap/query/customer
$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 |
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
You needed the API and Consumer Key as well as the Paybill Description.
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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request
Production: https://www.pesaswap.com/api/payment/request
$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);
$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
You needed the API and Consumer Key.
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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing
Production: https://www.pesaswap.com/api/payment/request/recurring/billing
$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);
$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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing
Production: https://www.pesaswap.com/api/payment/request/recurring/billing
$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);
$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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing
Production: https://www.pesaswap.com/api/payment/request/recurring/billing
$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);
$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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing
Production: https://www.pesaswap.com/api/payment/request/recurring/billing
$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);
$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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing
Production: https://www.pesaswap.com/api/payment/request/recurring/billing
$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);
$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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing
Production: https://www.pesaswap.com/api/payment/request/recurring/billing
$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);
$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 |
You needed the API and Consumer Key as well as the Paybill Description.
Sandbox: https://devpesaswap.azurewebsites.net/api/payment/request/recurring/billing
Production: https://www.pesaswap.com/api/payment/request/recurring/billing
$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);
$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
- 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
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
Airtel Collection Payment WALLET API - JSON Body
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
Airtel Disbursement Payment WALLET API - JSON Body
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
Balance Summary WALLET API - JSON Body
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.
- Please login to production site or sandbox site portal as merchant.
-
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.
- 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.
- 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
Sandbox: https://devpesaswap.azurewebsites.net/cybersource/payment-info
Production: https://www.pesaswap.com/checkout/cybersource/payment-info
Parameter
Description | Value | Mandatory |
---|---|---|
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? |
---|
|
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.
- 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:
- Click [Customers] sidebar menu, use search engine if needed.
- Click [eye] icon on the list
- 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
- Sandbox: https://devpesaswap.azurewebsites.net/api/generate-checkout-token
- Production: https://www.pesaswap.com/api/generate-checkout-token
$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.
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? |
---|
|
MPESA LIPA WALLET API
MPESA LIPA WALLET API - JSON Body
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
MPESA B2C WALLET API - JSON Body
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
Refund WALLET API - JSON Body
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
Transactions List WALLET API - JSON Body
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
- 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.
- Pesaswap Collection (Mpesa, Airtel, MTN-Momo) Woocommerce Plugin
- 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.
- 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:
- Click [Customers] sidebar menu, use search engine if needed.
- Click [eye] icon on the list
- 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
- Sandbox: https://devpesaswap.azurewebsites.net/api/generate-checkout-token
- Production: https://www.pesaswap.com/api/generate-checkout-token
$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.
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? |
---|
|
Checkout Page With Cybersource
Another secured payment checkout page is via cybersource. Please see details below.
- Please login to production site or sandbox site portal as merchant.
-
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.
- 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.
- 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
Sandbox: https://devpesaswap.azurewebsites.net/cybersource/payment-info
Production: https://www.pesaswap.com/checkout/cybersource/payment-info
Parameter
Description | Value | Mandatory |
---|---|---|
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? |
---|
|
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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/regular/card-payment
Production: https://www.pesaswap.com/api/regular/card-payment
$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
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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/coupon/payment
Production: https://www.pesaswap.com/api/coupon/payment
$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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/coupon/query
Production: https://www.pesaswap.com/api/coupon/query
$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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/interswitch/balance-inquiry
Production: https://www.pesaswap.com/api/interswitch/balance-inquiry
$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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/interswitch/transaction-inquiry
Production: https://www.pesaswap.com/api/interswitch/transaction-inquiry
$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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/interswitch/wallet-details
Production: https://www.pesaswap.com/api/interswitch/wallet-details
$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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/interswitch/wallet-transaction
Production: https://www.pesaswap.com/api/interswitch/wallet-transaction
$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 |
You needed the API and Consumer Key.
Sandbox: https://devpesaswap.azurewebsites.net/api/interswitch/get-wallet-provider
Production: https://www.pesaswap.com/api/interswitch/get-wallet-provider
$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.