This is initial step is to tell the SAG to initialise a payment you want to transact. After initialisation, you then make another request to the SAG as a confirmation prompt signaling the SAG to process the payment request requested.
Assuming Project Mulla is now your mediator, you’d now make a POST request to Project Mulla. Not Safaricom.
See below how you’d make this initial request:
POST
https://project-mulla-companyname.herokuapp.com/api/v1/payment/request
Body Parameters:
phoneNumber
- The phone number of your clienttotalAmount
- The total amount you are charging the clientreferenceID
[optional] - The reference ID of the order or servicemerchantTransactionID
[optional] - This specific order’s or service’s transaction IDNOTE: If
merchantTransactionID
orreferenceID
are not provided a time-based and random UUID is generated for each respectively.
Any extra body parameters of the POST request that is not part of the mandatory request
parameters will be considered to be extra payload and concatenated into one object before being
serialized and added as the ENC_PARAMS
SOAP parameter.
It will then eventually be sent back to you as a BASE64 string through the payment notification
POST request made to your provided MERCHANT_ENDPOINT
.
$ curl -i -X POST \
--url http://project-mulla-companyname.herokuapp.com/api/v1/payment/request \
--data 'phoneNumber=254723001575' \
--data 'totalAmount=45.00' \
--data 'clientName="Eugene Mutai"' \
--data 'clientLocation=Kilimani' \
If all goes well you get HTTP status code 200
accompanied with the a similar structed JSON response:
{
"response": {
"return_code": "00",
"status_code": 200,
"message": "Transaction carried successfully",
"trx_id": "453c70c4b2434bd94bcbafb17518dc8e",
"description": "success",
"cust_msg": "to complete this transaction, enter your bonga pin on your handset. if you don't have one dial *126*5# for instructions",
"reference_id": "3e3beff0-fc05-417a-bbf2-190ee19a5e58",
"merchant_transaction_id": "95d64500-2514-11e6-bcb8-a7f8e1c786c4",
"amount_in_double_float": "45.00",
"client_phone_number": "254723001575",
"extra_payload": {
"clientName": "Eugene Mutai",
"clientLocation": "Kilimani"
},
"time_stamp": "20160528234142"
}
}
You are to use trx_id
or merchant_transaction_id
to make the confirmation payment
request. The confirmation request is the request the payment requested above to be processed and
triggers a pop up on the your client’s mobile phone.
When one now pings the endpoint /payment/request it initializes the payment and when Safaricom responds with a HTTP status 200 and a payload, Project Mulla now automatically confirms the payment by also hitting the endpoint payment/confirm
This means you no longer have to make a second call to Project Mulla to confirm the payment thus hitting up the user’s phone with the USSD prompt. One call to payment/request should handle this automatically.