Skip to content

Latest commit

 

History

History
162 lines (142 loc) · 7.8 KB

README.md

File metadata and controls

162 lines (142 loc) · 7.8 KB

Safaricom Express(USSD Push)

Express initiates online payment on behalf of the customer using USSD Push.

1. Authentication

1.1 Register for a Safaricom Developer Account

For authentication credentials to be used only for the sandbox, Safaricom Developer Account is required. To log in or register, go to https://developer.safaricom.co.ke/. The Organization Information must be provided when applying for new credentials when going live.

1.2 Create an app

Using https://developer.safaricom.co.ke/MyApps, you can create an app and select the Lipa Na M-Pesa and M-Pesa Sandbox check boxes. By creating an app, you can obtain the Consumer Key and Consumer Secret that will be used for Basic Authentication.

Step 1: Get Access Token using Basic Auth

METHOD GET
URL Sandbox: https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials
Successful Request
curl --location --request GET 'http://localhost:8080/accessToken'
Request Fields
NAME DESCRIPTION TYPE
authorization Basic Authentication over HTTPS, this is a base64 encoded string of your app’s consumer key and consumer secret Header
grant_type client _credentials grant type is supported. Put this under params Query

Successful Response

{
    "access_token": "ZPRHAAXD1oaZ1gp9EdXFGVfw8Gv6",
    "expires_in": "3599"
}
Response Fields
NAME DESCRIPTION TYPE
access_token Access token used to access the customer to business payments api JSON
expires_in Token expiry time in seconds JSON

Step 2: Initiate an express(USSD Push) payment

METHOD POST
URL Sandbox: https://sandbox.safaricom.co.ke/mpesa/stkpush/v1/processrequest
Successful Request
curl --location --request POST 'http://localhost:8080/stkPush' \
--header 'Content-Type: application/json' \
  --data-raw '{
"Amount": 1,
"PhoneNumber": 2547484581XX
}'
Request Fields
NAME DESCRIPTION TYPE
Amount The amount transacted normally integer value Integer
PhoneNumber The Mobile Number to receive the USSD Pin Prompt Integer

Successful Response

{
  "MerchantRequestID": "68444-143235050-2",
  "CheckoutRequestID": "ws_CO_22112022152650652748458100",
  "ResponseCode": "0",
  "ResponseDescription": "Success. Request accepted for processing",
  "CustomerMessage": "Success. Request accepted for processing"
}
Response Fields
NAME DESCRIPTION TYPE
MerchantRequestID This is a globally unique identifier for any submitted payment request String
CheckoutRequestID This is a globally unique identifier of the processed checkout transaction request String
ResponseDescription An acknowledgement message from API that gives the status of the request submission usually maps to a specific ResponseCode value Numeric
ResponseCode This is a Numeric status code that indicates the status of the transaction submission. 0 means successful submission and any other means code means an error occurred Numeric
CustomerMessage This is a message that your system can display to the Customer as an acknowledgment of the payment request submission String

Data sent to the Callback URL

{
  "Body": {
    "stkCallback": {
      "MerchantRequestID": "68444-143235050-2",
      "CheckoutRequestID": "ws_CO_22112022152650652748458100",
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          {
            "Name": "Amount",
            "Value": 1
          },
          {
            "Name": "MpesaReceiptNumber",
            "Value": "QKM0FXE6RK"
          },
          {
            "Name": "TransactionDate",
            "Value": 20221122152706
          },
          {
            "Name": "PhoneNumber",
            "Value": 2547484581XX
          }
        ]
      }
    }
  }
}

Step 3: Express Query Status

METHOD POST
URL Sandbox: https://sandbox.safaricom.co.ke/mpesa/stkpushquery/v1/query
Successful Request
curl --location --request POST 'http://localhost:8080/stkPush/status' \
--header 'Content-Type: application/json' \
  --data-raw '{
"CheckoutRequestID": "ws_CO_22112022164548577748458100"
}'
Request Fields
NAME DESCRIPTION TYPE
CheckoutRequestID This is a globally unique identifier of the processed checkout transaction request Integer

Successful Response

{
  "ResponseCode": "0",
  "ResponseDescription": "The service request has been accepted successsfully",
  "MerchantRequestID": "5468-13551780-2",
  "CheckoutRequestID": "ws_CO_22112022164548577748458100",
  "ResultCode": "0",
  "ResultDesc": "The service request is processed successfully."
}
Response Fields
NAME DESCRIPTION TYPE
ResponseCode 0 means successful submission Integer
ResponseDescription Acknowledgment message of successful submission request String
MerchantRequestID Timestamp of the transaction with format(YEAR+MONTH+DATE+HOUR+MINUTE+SECOND) Timestamp
CheckoutRequestID Global unique identifier of the processed transaction checkout String
ResultCode 0 means successful transaction by customer, any other means an error occurred. Integer
ResultDesc Acknowledgment message describing the transaction status String

Error Codes

ERROR CODE DESCRIPTION
404.001.03 Invalid access token
500.001.1001 Transaction already in process