1. Instant Payment Notification (C2B)

On receiving a transaction, Sapama Cash will instantly send you the notification to the "Instant Payment Notification (IPN)" settings set under the till.

Sample Code:
PHP

Step 1:

  1. Login to your Sapama Cash account or click on this link
  2. Click on Tills menu or click this link
  3. In the far right of the till, click on this "Edit" icon
  4. Go to the "Instant Payment Notification (IPN)" section
  5. Set the "Callback active" to "Yes"
  6. Set the "Callback HTTP method" of your URL ie POST or GET
  7. Set the "Callback url" that your want payment notification will be sent with http://, https:// or IP as. eg http://sapamacash.com/payment_notification
  8. Optional: If you want us to pass extra parameters in the request, set them as valid JSON in the "Extra parameters (JSON)" eg
    {"property_ids":[728,729,735]}

Step 2:

Implement your code to listen to the notification

We'll post the following

                {
                "trans_type": "PayBill",
                "trans_id": "979790", //MPESA transaction id
                "trans_time": "2016-11-21 20:45:35", // MPESA transaction time (Y-m-d H:m:s)
                "date": "2016-11-21", // MPESA transaction date (Y-m-d)
                "trans_amount": "123.00",
                "short_code": "830830",
                "bill_ref_number": "TX1001", //MPESA Account number 
                "org_account_balance": "12345.00",// MPESA 
                "phone": "254722906835",
                "first_name": "Hoiyor", 
                "middle_name": "G",
                "last_name": "Chen",
                "organization_id": 1,
                "customer_id": 1,//Customer id on our Sapama Cash system
                "location_id": 1, //Till or paybill number id on Sapama Cash system
                "proxy_trans_id": 1 //Transaction id on Sapama Cash system
                }    
            

If you are using PHP, you can capture the fields like this or download this sample PHP

                if( isset( $_POST['trans_type'] ) &&  strlen( $_POST['trans_type'] )){
                $trans_type = $_POST['trans_type'];
                }

                if( isset( $_POST['trans_amount'] ) &&  strlen( $_POST['trans_amount'] )){
                $trans_amount = $_POST['trans_amount'];
                }
            

Step 3:

For the handshake to be complete, after processing the transaction on your end, kindly return or echo the following JSON object so that we can update the transaction as reconciled on your end.
                {
		"type": "success",
		"message": "Transaction reconciled successfully"
                }
            
The "type" index can have the following values:
                no : 'Not yet ipned. This is the default status',
                success:'Successfully recorded in your system',
                error:'A System error occurred when trying to reconcile',
                unreconciled:'An error occurred when trying to reconcile eg that transaction is in SapamaCash.com but not in your system',
            

Step 4:

To send or simulate a transaction, you don't have to make an actual MPESA or Equitel transaction every time, if there are no transaction, make one actual transaction, and UPDATE it as long as the ipned status IS NOT equal to "success" by click on this "Edit" icon . The system will send or push the transaction to your server. Kindly note that if the ipned status is "success", the IPN WILL NOT be sent

2. Custom SMS

On receiving a transaction, Sapama Cash can send a customised SMS to your customer.

Step 1:

  1. Login to your Sapama Cash account or click on this link
  2. Click on Tills menu or click this link
  3. In the far right of the till, click on this "Edit" icon
  4. Go to the "Instant Payment Notification (IPN)" section
  5. Set the "Thank customers" to "Yes"
  6. Set your "Sms gateway". For new accounts this should be "Africa's Talking"
  7. Set your "Sms sender id / Alphanumeric". This is the custom name that will be used. This customer name needs to be registered with Africa's Talking
  8. Set the "Sms template" and use the following placeholders. All parameters are prepended with a : (full colon)
  9. FIELDS ARE CASE SENSITIVE
  10.                         :name - Customer name
                            :currency - 'KES',
                            :amount - Transaction amount
                            :points - Points if running a loyalty scheme,
                            :transid - MPESA or Equitel transaction code
                            :proxytransid - Sapama Cash transaction id,
                            :billrefnumber - MPESA or Equitel account number,
                            :date - transaction date in d/m/Y fromat ,
                            :location' - Name of the till
                    

3. Get Transactions

Get transactions

Link:
http://sapamacash.com/api/get_transactions
HTTP TYPE:
GET
Sample Code:
PHP

Parameters

# Field Data type Note Required / Optional
1 format string Must be 'json' 1
2 api_key string API key 1
3 hash string Hash 1
4 trans_id string MPESA confirmation Code 0
5 phone integer Customer phone number with 254 and without + eg 25472200000 0
6 page integer The page of the pagination to return eg page 1, 2 0
7 per_page integer Number of transactions to be returned to return in a given page eg return 20 transactions (Defaults to 50) 0

Returns

Action Http status code Note Example
Success 200 List of transactions
{"httpStatusCode":200,"systemCode":700,"message":"Transactions list","data":{"total":42,"per_page":3,"current_page":1,"last_page":14,"from":1,"to":3,"data":[{"id":451,"organization_id":2,"customer_id":193,"location_id":2,"category_id":0,"trans_type":"Pay Bill","trans_id":"LBA022D4JK","trans_time":"2017-02-10 18:56:42","date":"2017-02-10","trans_amount":"17,000.00","short_code":"830830","bill_ref_number":"501007001748","invoice_number":"","org_account_balance":"121,601.00","third_party_trans_id":"","phone":"254729306807","name":"ANNE NYOKABI MUCHUKU","first_name":"ANNE","middle_name":"NYOKABI","last_name":"MUCHUKU","ipned":"no","smsed":"","emailed":"","ipned_at":"0000-00-00 00:00:00","smsed_at":"0000-00-00 00:00:00","emailed_at":"0000-00-00 00:00:00","customer_thanked_at":"2017-02-10 15:58:05","customer_thanked":"y","thank_you_message":"Dear Anne Nyokabi Muchuku, Thank you for making payment of KES 17,000 at Sapama Shop. You have 8500 loyalty points. Redeem them on Friday. We value you.","smsed_to":"","emailed_to":"","workflow":1,"agent":"Agent","ip":"127.0.0.1","status":1,"created_by":1,"updated_by":1,"created_at":"2017-02-10 18:58:02","updated_at":"2017-02-10 18:58:05","third_party_message":"","payload_response":"","payload_count":0,"category":null},{"id":401,"organization_id":2,"customer_id":162,"location_id":2,"category_id":0,"trans_type":"Pay Bill","trans_id":"LB86171DEU","trans_time":"2017-02-08 08:27:23","date":"2017-02-08","trans_amount":"10.00","short_code":"830830","bill_ref_number":"830830","invoice_number":"","org_account_balance":"104,601.00","third_party_trans_id":"","phone":"254725988791","name":"BALLON  MWENI","first_name":"BALLON","middle_name":"","last_name":"MWENI","ipned":"no","smsed":"","emailed":"","ipned_at":"0000-00-00 00:00:00","smsed_at":"0000-00-00 00:00:00","emailed_at":"0000-00-00 00:00:00","customer_thanked_at":"2017-02-08 05:27:46","customer_thanked":"y","thank_you_message":"Dear Ballon  Mweni, Thank you for making payment of KES 10 at Sapama Shop. You have 5 loyalty points. Redeem them on Friday. We value you.","smsed_to":"","emailed_to":"","workflow":1,"agent":"Agent","ip":"127.0.0.1","status":1,"created_by":1,"updated_by":1,"created_at":"2017-02-08 08:27:42","updated_at":"2017-02-08 08:27:46","third_party_message":"","payload_response":"","payload_count":0,"category":null},{"id":380,"organization_id":2,"customer_id":149,"location_id":2,"category_id":0,"trans_type":"Pay Bill","trans_id":"LB63ZQFMQT","trans_time":"2017-02-06 18:47:07","date":"2017-02-06","trans_amount":"8,400.00","short_code":"830830","bill_ref_number":"501007001898","invoice_number":"","org_account_balance":"112,991.00","third_party_trans_id":"","phone":"254727929342","name":"MONICA  MWANGI","first_name":"MONICA","middle_name":"","last_name":"MWANGI","ipned":"no","smsed":"","emailed":"","ipned_at":"0000-00-00 00:00:00","smsed_at":"0000-00-00 00:00:00","emailed_at":"0000-00-00 00:00:00","customer_thanked_at":"2017-02-06 15:47:18","customer_thanked":"y","thank_you_message":"Dear Monica  Mwangi, Thank you for making payment of KES 8,400 at Sapama Shop. You have 4200 loyalty points. Redeem them on Friday. We value you.","smsed_to":"","emailed_to":"","workflow":1,"agent":"Agent","ip":"127.0.0.1","status":1,"created_by":1,"updated_by":1,"created_at":"2017-02-06 18:47:15","updated_at":"2017-02-06 18:47:18","third_party_message":"","payload_response":"","payload_count":0,"category":null}]}}
Error 400 Validation error
{
  "http_status_code": 400,
  "system_code": 900,
  "message": "Input validation failed.",
  "data": [
    {
      "field": "token",
      "error": "Invalid login token"
    }
  ]
}

4. Update Transaction

Get transactions

Link:
http://sapamacash.com/api/update_transaction
HTTP TYPE:
POST
Sample Code:
PHP

Parameters

# Field Data type Note Required / Optional
1 format string Must be 'json' 1
2 api_key string API key 1
3 hash string Hash 1
4 id integer The transaction id (Not MPESA transaction id) 1
5 ipned string no : 'Not yet ipned. This is the default status',
success:'Successfully recorded in your system',
error:'A System error occurred when trying to reconcile',
unreconciled:'An error occurred when trying to reconcile eg that transaction is in SapamaCash.com but not in your system',
1

Returns

Action Http status code Note Example
Success 200 Transaction updated
{"httpStatusCode":200,"systemCode":700,"message":"Transaction updated","data":{"id":"1"}}
Error 400 Validation error
{"httpStatusCode":400,"systemCode":900,"message":"Input validation failed.","data":[{"field":"api_key","error":"Invalid hash"}]}

5. B2C (Business to Customer)

API to make Business to Customer transaction ie pay a customer directly from your account to their mobile money account

Link:
http://sapamacash.com/api/b2c
HTTP TYPE:
POST
Sample Code:
PHP

Parameters

# Field Data type Note Required / Optional
1 format string Must be 'json' 1
2 api_key string API key 1
3 hash string Hash 1
4 location_id integer The location id get this by logging in a going to Tills and using number in the first column or # 1
5 mode string live : Production or live environment
sandbox:Sandbox or test environment
1
6 beneficiaries array

Parameters / indexes / keys in the beneficiary

# Field Data type Note Required / Optional
1 gateway string mpesa : Payout via MPESA
equitel :Payout via Equitel
1
2 phone integer phone number to payout to including country code eg 254722906835 1
3 trans_reference string Transaction reference. This is the unique identifier of this transaction on your system. We'll send it back so that you can identify this transaction eg TRANXYZ 1
4 description string Description eg Salary 1
5 first_name string First name eg Otieno 1
6 last_name string Last name eg Kamau 1
7 amount float Amount eg 100.55 1
8 callback_url url Callback URL to return the status of the transaction after sending to the gateway for processing eg http://sapamacash.com/receive_b2c_notification 1
9 callback_http_method string HTTP method to call the callback with get : GET to the callback URL
post:POST to the callback URL
1
10 message string Custom message that will be sent via SMS AFTER a successful transaction. You can also set it in the B2C template under the till eg Thanks you Kamau for making the payment. 1
11 short_code integer Gateway short code eg For MPESA, use Paybill number 1
12 currency string currency code eg KES 1
1

Returns

Action Http status code Note Example
Success 200 1 of 1 (100%) scheduled for B2C
{"httpStatusCode":200,"systemCode":700,"message":"1 transactions of 1 (100%) scheduled for B2C","data":[{"status":"success","message":"Success","proxy_trans_id":12376,"phone":"254722906835","amount":"10"}]}
Error 400 Validation error
{"httpStatusCode":400,"systemCode":900,"message":"Input validation failed.","data":[{"field":"beneficiaries","error":"trans_reference at beneficiaries 0 should be set and it identifies this transaction on your system. Best if it's unique"}]}

6. Checkout

This API is used to checkout.

Link:
http://sapamacash.com/api/checkout
HTTP TYPE:
POST
Sample Code:
PHP

Parameters

# Field Data type Note Required / Optional
1 format string Must be 'json' 1
2 api_key string API key 1
3 hash string Hash 1
4 location_id integer The location id get this by logging in a going to Tills and using number in the first column or # 1
6 to array

Parameters / indexes / keys in the beneficiary

# Field Data type Note Required / Optional
1 phone integer phone number to payout to including country code eg 254722906835 1
2 message string SMS Message eg \'Hello Customer'\ 1
1

Returns

Action Http status code Note Example
Success 200 1 of 1 (100%) scheduled for SMS
{"httpStatusCode":200,"systemCode":700,"message":"1 smses of 1 (100%) scheduled for sending","data":[{"status":"success","message":"Success","proxy_trans_id":12376,"phone":"254722906835","amount":"10"}]}
Error 400 Validation error
{"httpStatusCode":400,"systemCode":900,"message":"Input validation failed.","data":[{"field":"beneficiaries","error":"trans_reference at beneficiaries 0 should be set and it identifies this transaction on your system. Best if it's unique"}]}

7. SMS

API to send SMS to an array of phone numbers. Messages can be different for each phone number

Link:
http://sapamacash.com/api/sms
HTTP TYPE:
POST
Sample Code:
PHP

Parameters

# Field Data type Note Required / Optional
1 format string Must be 'json' 1
2 api_key string API key 1
3 hash string Hash 1
4 location_id integer The location id get this by logging in a going to Tills and using number in the first column or # 1
6 to array

Parameters / indexes / keys in the beneficiary

# Field Data type Note Required / Optional
1 phone integer phone number to payout to including country code eg 254722906835 1
2 message string SMS Message eg \'Hello Customer'\ 1
1

Returns

Action Http status code Note Example
Success 200 1 of 1 (100%) scheduled for SMS
{"httpStatusCode":200,"systemCode":700,"message":"1 smses of 1 (100%) scheduled for sending","data":[{"status":"success","message":"Success","proxy_trans_id":12376,"phone":"254722906835","amount":"10"}]}
Error 400 Validation error
{"httpStatusCode":400,"systemCode":900,"message":"Input validation failed.","data":[{"field":"beneficiaries","error":"trans_reference at beneficiaries 0 should be set and it identifies this transaction on your system. Best if it's unique"}]}