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

REQUIREMENT	DESCRIPTION
1. Merchant_id	This is a unique identification created by NALO for third parties doing the integration
2. Username	This is the account name for the client. Required with a password when accessing the online portal
3. Password	The password to the user account generated by NALO
4. Endpoint	https://api.nalosolutions.com/payplus/api/
5. Content type	Application/json
6. Gateway IP	The IP address(es) of the host from which the request will be originating. This is required for authentication
7. Method	POST

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

PARAMETERS	DESCRIPTION	FORMAT (length)
1. merchant_id	The merchant_id is generated by NALO and is required to make a successful request. Eg: NPS_000551	STRING (10)
2. key	Randomly generated 4 digits used in generating the secret	STRING (4)
3. secrete	The 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_id	The unique identification for the payment order. This is also generated at the client-side and will be returned in the charging response.	STRING
5. customerName	The name of the payment authorizer or the buyer. Eg. Gideon Nana Kwesi	STRING
6. amount	This is the invoice amount stated in units of Ghanaian cedis. Note: the amount should be used with the currency. Eg. 2.00	NUMERIC
7. item_desc	The 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 prefixed	NUMERIC (12)
9. callback	The callback URL of the client that will be called to pass payment response	STRING
10. payby	This option tells which network operator the authorizer is subscribed to. Available options are: MTN, AIRTELTIGO, VODAFONE	STRING
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"
        }
        

ELEMENT	DESCRIPTION	FORMAT (length)
1. Timestamp	This indicates the time period when the request was processed by the gateway	TIMESTAMP
2. Status	This indicates whether the transaction was successfully processed or not. Status is either ACCEPTED or FAILED with description	STRING
3. InvoiceNo	This is a unique number generated by the gateway to match the request. It is only available for transactions with Accepted status	STRING
4. Order_id	This 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"
            }