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

Update transaction

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"}]}

4. Post a transaction. It will create a record in the transactions table

Get transactions

Link:
http://sapamacash.com/api/post_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 first_name string First name 0
5 middle_name string Middle name 0
6 last_name string Last name 0
7 trans_type string Transaction type 0
8 trans_id string Unique transaction reference number. Should be unique to avoid duplication 1
9 trans_time string in this format Y:m:d H:i:s 1
10 trans_amount float The amount 1
11 short_code string Used to identify the this till
12 org_account_balance float The account balance
13 phone int Phone number
14 bill_ref_number string Same as account or customer number 0
15 invoice_number string Invoice number 0
16 description string Note 1
17 third_party_trans_id string Unique identifier on your system eg primary key on your system 0

Returns

Action Http status code Note Example
Success 200 Transaction updated
{"httpStatusCode":200,"systemCode":700,"message":"Succeed.","data":[{"third_party_trans_id":"third_party_trans_id","trans_id":"trans_id","sapama_id":290047,"type":"success","message":"Success"}]}
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_id string Transaction id. 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 first_name string First name eg Otieno 1
5 description string Description eg Salary 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. 0
11 short_code integer Gateway short code eg For MPESA, use Paybill number 1
12 currency string currency code eg KES 1
13 bill_ref_number string Another number that can be used to reference this transaction eg the customers account number or user id 0
1

Returns

Action Http status code Note Example
Success 200 we turn an array in the "data" parameter. Loop through it and check for the "trans_id" that will be used to
{
    "httpStatusCode": 200,
    "systemCode": 700,
    "message": "2 transactions of 2 (100%) scheduled for B2C",
    "data": [
        {
            "status": "success",
            "message": "Success",
            "proxy_trans_id": 305528,
            "trans_id": "trans_reference",
            "phone": "0722906830",
            "amount": "100"
        },
        {
            "status": "success",
            "message": "Success",
            "proxy_trans_id": 305529,
            "trans_id": "trans_reference",
            "phone": "0722906832",
            "amount": "100"
        }
    ]
}
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"}]}