Paytalk Mobile Payment Documentation - Lipa Na Mpesa

Paytalk Lipa Na Mpesa WooCommerce Extension


Introduction


Paytalk is a finance management system, helping you with mobile money integrations (C2B, B2C & B2B). Paytalk enables your software (website, mobile app, desktop app etc) to communicate with Mpesa servers using our available API keys. API keys can be generated and managed in your Paytalk developer account https://developer.paytalk.co.ke/
Below are the documentations on how to use Paytalk Lipa Na Mpesa WooCommerce Extension. Kindly note that each release of this extension would have its own documentation, therefore, you should always take note of the version number.


Paytalk Lipa Na Mpesa WooCommerce Extension – 1.5.0

VERSION – 1.5.0

  1. Create Paytalk developer account
    Head to https://developer.paytalk.co.ke/ and create an account. You will be required to provide basic information about yourself.
  2. Login to your developer account
  3. The first page that you will see would be an empty table; below it is a form for creating your project. Go ahead and create a project. Make sure you fill in valid and correct information before generating your keys. In case of wrong inputs, you will have to delete your project and start all over again.
  4. Once you have generated your keys in the project you created, go ahead to ‘Check Status’ and provide Paybill/Till number information (Organization name, the phone that is associated with that Paybill/Till number, store number).
  5. Once you have provided the Paybill/Till Number information, your project status will switch to ‘processing’ state. Meaning that Paytalk system is trying to communicate with Mpesa APIs. In a rare occasion when Paytalk system is unable to automatically communicate with Mpesa APIs, one of our agents will be assigned to you for faster processing.
  6. In the meantime, while your project is still processing, you can use Test Mode APIs.
  7. Head to your Site and install Paytalk Lipa Na Mpesa plugin. Skip this step if already installed and activated.

    8. Download Paytalk Lipa Na Mpesa Plugin
    INSTALLATION

    • Method 1- Using FTP
      1. Unzip the downloaded file and upload to your WordPress plugin directory(wp-contents/plugins/). Then, go to your WordPress admin backend, in the plugins section, you will see Paytalk Lipa Na Mpesa. Activate it.
    • Upload via WordPress 'add new' plugin in your admin backend.
    • ACTIVATION
      1. Go to WooCommerce => Settings
      2. On the “Settings” page, select “Payment Gateways” tab.
      3. Under “Payment Gateways” you will find all the available gateways, select “PayTalk.co.ke” option
      4. On this page, you will find options to configure the plugin for use with WooCommerce
  8. Enter the API details with the Paybill/Till number registered on your Paytalk developer account. Copy Test Mode API keys and paste on Paytalk Lipa Na Mpesa WooCommerce gateway, then enable test mode. The test mode will let you know if you are connected with Paytalk’s developer account. In case you get an error, read through the error and rectify as instructed.
  9. Once you have tested and made sure no errors popping up, and your project has completed processing, you can then change the APIs to LIVE.

Use version 1.5.2 documentation

Paytalk Lipa Na Mpesa WooCommerce Extension – 1.5.2

VERSION – 1.5.2

  1. Create Paytalk developer account
    Head to https://developer.paytalk.co.ke/ and create an account. You will be required to provide basic information about yourself.
  2. Login to your developer account
  3. The first page that you will see would be an empty table; below it is a form for creating your project. Go ahead and create a project. Make sure you fill in valid and correct information before generating your keys. In case of wrong inputs, you will have to delete your project and start all over again.
  4. Once you have generated your keys in the project you created, go ahead to ‘Check Status’ and provide Paybill/Till number information (Organization name, the phone that is associated with that Paybill/Till number, store number, indicate whether it is paybill or till number). You may also send these details to info@paytalk.co.ke for a faster response frm a human :-).
  5. Once you have provided the Paybill/Till Number information, your project status will switch to ‘processing’ state. Meaning that Paytalk system is trying to communicate with Mpesa APIs. In a rare occasion when Paytalk system is unable to automatically communicate with Mpesa APIs, one of our agents will be assigned to you for faster processing.
  6. Head to your Site and install Paytalk Lipa Na Mpesa plugin. Skip this step if already installed and activated.
  7. To test to see if your site is communicating with paytalk gateway, use Test APIs.
  8. Once your paybill/till number has succesfully been integrated, you will need to change API keys on your site to reflect Live API keys of your project.
  9. In the meantime, while your project is still processing, you can still use Live API keys. In this case, check 'offline mode' in your plugin.
  10. With offline mode activated, all transactions made on your website will appear here.
    11. For enquiries and support, please write to info@paytalk.co.ke and cc developer@paytalk.co.ke

cURL Documentation

$environment = ( $yourTestVariable == "yes" ) ? 'TRUE' : 'FALSE';

// Decide which URL to post to
$environment_url = ( "FALSE" == $environment )
? 'https://developer.paytalk.co.ke/api/'
: 'https://developer.paytalk.co.ke/api/';

$payload = [
// Paytalk.co.ke Credentials and API Info
"trans_key" => "Your API transaction Key",
"api_user" => "Your API User Key",
"paytill" => "Your Paybill/Till number",
"x_version" => "1.5.0",
"x_amount" => "Total Amount Payable",

// Lipa Na Mpesa Information "mpesa_code" => "Mpesa Trensaction ID",
"mpesa_phone" => "Phone number",

"x_type" => 'AUTH_CAPTURE',
"x_invoice_num" => "Your invoice/order number",
"x_test_request" => $environment,
"x_delim_char" => '|',
"x_encap_char" => '',
"x_delim_data" => "TRUE",
"x_relay_response" => "FALSE",
"x_method" => "mpesa",
"order_id" => "Get order id",
"x_customer_ip" => $_SERVER['REMOTE_ADDR']
];

$data = json_encode($payload);
$environment_url = "htts://developer.paytalk.co.ke/apis/";
$ch = curl_init();
$curlConfig = array(
CURLOPT_URL => $environment_url,
CURLOPT_HTTPHEADER => array('Content-Type: application/json'),
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => $data
);
curl_setopt_array($ch, $curlConfig);
curl_setopt($ch,CURLOPT_SSL_VERIFYPEER, true);
$response = curl_exec($ch);
curl_close($ch);

Required variables

  1. API Username - api_user
  2. API Transaction Key - trans_key
  3. Amount - x_amount
  4. Mobile Number - mpesa_phone
  5. Transaction ID - mpesa_code
  6. Invoice/Order ID - order_id

Important: You cannot run the sample requests in this guide as-is. Replace call-specific parameters such as API Keys and Paybill/Till Number with your own values.

API responses

PayTalk API calls return HTTP status codes. Some API calls also return JSON response bodies that include information about the resource including one or more contextual links. Use these links to request more information about and construct an API flow that is relative to a specific request.

HTTP status responses

In the responses, PayTalk returns one of the following responses:

Status Description
Empty - ""//Null response Unable to verify payment
no_account "no_account" Unable to verify your API keys
Numeric Value is_numeric() Payment made was below the expected amount
no_trans "no_trans" Transaction ID/ Phone number error
Success "Success" Payment verified

HTTP REQUEST

For HTTP Request, do a POST to the following URL;
https://developer.paytalk.co.ke/apis/?api_user="YOUR_API_USERNAME"&trans_key="YOUR_API_TRANSACTION_KEY"&x_amount="CAPTURED_AMOUNT"&mpesa_phone="CUSTOMER_PHONE_NUMBER"&mpesa_code="TRANSACTION_ID&order_id="INVOICE/ORDER_NUMBER_ID"