Payment API Documentation

NALO’s payment API, Payplus allows a platform for payments between merchants and buyers. Make a request here to set up. Buying goods online is a convenient but often frustrating experience, particularly on mobile devices. Although mobile traffic continues to increase, mobile conversions account for only about a third of all completed purchases. In other words, users abandon mobile purchases twice as often as desktop purchases. Why?

Prerequisite #

To successfully complete the integration the following details are required as described in table 1.0 below:


TABLE 1.0

REQUIREMENTDESCRIPTION
1. Merchant_idThis is a unique identification created by NALO for third
parties doing the integration
2. UsernameThis is the account name for the client. Required with a password when accessing the online portal
3. PasswordThe password to the user account generated by NALO
4. Endpointhttps://api.nalosolutions.com/payplus/api/
5. Content typeApplication/json
6. Gateway IPThe IP address(es) of the host from which the request will
be originating. This is required for authentication
7. MethodPOST

General Payment Flow #

  1. User provides a wallet number and initiates a request.
  2. Upon receipt, we send an OTP to the user for confirmation.
  3. The user verifies the transaction by dialling the shortcode in the OTP received.
  4. Bill prompt is sent to the user once we confirm OTP.

NB: Requests from clients using NALO USSD do not come with OTP. Bill prompts are sent to the user’s handset once we receive the request.

Making Payment –Initiation Request #

To successfully initiate payment, all required parameters must be present and successfully validated in the request. The request is JSON formatted and must contain the following as described in table 2.0 below:

TABLE 2.0

PARAMETERSDESCRIPTIONFORMAT (length)
1. merchant_idThe merchant_id is generated by NALO and is required to make a successful request. Eg: NPS_000551STRING (10)
2. keyRandomly generated 4 digits used in generating the secretSTRING (4)
3. secreteThe secrete is required to authenticate the client. This is generated at the client’s side as a concatenation
of the username, key and md5 hash of the password all hashed in md5. Eg. md5($username.$key. md5($password))
STRING
4. order_idThe unique identification for the payment order. This is also generated at the client-side and will be returned
in the charging response.
STRING
5. customerNameThe name of the payment authorizer or the buyer. Eg. Gideon Nana KwesiSTRING
6. amountThis is the invoice amount stated in units of Ghanaian cedis. Note: the amount should be used with the currency. Eg. 2.00NUMERIC
7. item_descThe description of the purchased item or service. Eg. bulk SMS
8. customerNumber This is the billing mobile number (msisdn) in the format of 233xxxxxxxx. Note: msisdn should always be prefixedNUMERIC (12)
9. callbackThe callback URL of the client that will be called to pass payment responseSTRING
10. paybyThis option tells which network operator the authorizer is subscribed to. Available options are: MTN, AIRTELTIGO, VODAFONESTRING
11. newVodaPayment Vodafone Payments Only (Optional)Vodafone provides two types of payment options. A USSD popup and
Vodafone Payments a voucher input generated by the
BOOLEAN
12. isussd(optional)This parameter indicates if the request is coming from a NALO USSD extension. Set value to 1 when coming from the USSD, else set 0.BOOLEAN

Sample request data format: #


    {
        "merchant_id": "NPS_000002",
        "secrete":  "9224 a7c40510214c392f9fb93714d38f",
        "key": "0626",
        "order_id": "myoder_15150",
        "customerName": "Gideon",
        "amount": "5",
        "item_desc":  "Voucher Code" ,
        "customerNumber": "233241000000",
        "payby": "VODAFONE",
        "callback": "https: //mycallbackurl.com/callback/"
    }
    

Vodafone Payment #

The Vodafone payment process is quite different from the usual payment. There are mainly two modes. The default process requires that users generate a voucher code before proceeding else the transaction fails.

The other mode shows a USSD bill prompt for the user to input a pin after providing their details.

Vodafone Payment Request Sample #

When making a request, item_desc holds the voucher code generated by the user. Sample request data format:

      
    {
        "merchant_id": "NPS_000002",
        "secrete": "9224 a7c40510214c392f9fb93714d38f",
        "key": "0626",
        "order_id": "myoder_15150",
        "customerName": "Gideon",
        "amount": "5",
        "item_desc": "Voucher Code",
        "customerNumber": "233241000000",
        "payby": "VODAFONE",
        "callback": "https: //mycallbackurl.com/callback/"
    }

Sample request data format for the new vodafone payment: #


        {
            "merchant_id": "NPS_000002",
            "secrete": "9224 a7c40510214c392f9fb93714d38f",
            "key": "0626",
            "order_id": "myoder_15150",
            "customerName": "Gideon",
            "amount": "5",
            "item_desc": "Vodafone Payment",
            "customerNumber": "233241000000",
            "payby": "VODAFONE",
            "newVodaPayment": true,
            "callback": "https: //mycallbackurl.com/callback/"
        }
    

Response To Request #

The response to the request is also a JSON data format as shown in the example below:


        {
            "Timestamp": "2018-01-04 11:24:47",
            "Status": "Accepted",
            "InvoiceNo": "203343123",
            "Order_id": "myoder_15150"
        }
        
ELEMENTDESCRIPTIONFORMAT (length)
1. TimestampThis indicates the time period when the request was processed by the gatewayTIMESTAMP
2. Status This indicates whether the transaction was successfully processed or not. Status is either ACCEPTED or FAILED with descriptionSTRING
3. InvoiceNoThis is a unique number generated by the gateway to match the request. It is only
available for transactions with Accepted status
STRING
4. Order_idThis is the unique ID generated from the client’s side to match the request.STRING

Callback Response #

The callback response is sent once we receive and process a payment request. The callback response is JSON data which is sent via the callback URL received as part of the INITIATION REQUEST. The data is sent via a POST request with the same parameters as the RESPONSE to the payment initiation request with the appropriate status.

See example below: #


        {
            "Timestamp": "2018-01-04 11:24:47",
            "Status": "PAID",
            "InvoiceNo": "203343123",
            "Order_id": "myoder_15150"
        }
        

For a failed transaction, below is the response: #


        {
            "Timestamp": "2018-01-04 11:24:47",
            "Status": "FAILED",
            "InvoiceNo": "203343123",
            "Order_id": "myoder_15150"
        }
        

Callback Response #

The response to the callback is static as shown below:


            {
                "Response": "OK"
            }
        

Powered by BetterDocs

Scroll to Top