Account Validation

The EllyPay API platform has a pre-requisite that before a payment is made for any of the products, the recipient account needs to be validated to confirm the name. The section describes as follows;

We recommend checking out the Getting Started section to understand the basics of service payments first and the general workflow. This guide assumes that you have read that

Step 1: Obtain the required data for the validation request

The table below describes the request parameters that are used for the account validation request. Most/all will be collected from the paying customer.

Parameter	Type	Required	Description
merchant_reference	String	true	The unique reference for this request. It must be at least 8 characters long. You can pass the value as auto and the API will generate a reference on your behalf
account_number	String	true	The account number to be validated. This can be the airtime/internet phone number, Yaka Meter Number, NWSC Meter Number, URA PRN or any identifier whose account details are required
service_code	String	true	The unique service code. For services with price/package lists, use the item code from the packages list otherwise use the code from the main service list
currency	String	true	The 3-character ISO currency code for the request currency
amount	Number	true	The amount to be transferred
additional_params	Object	false	This parameter normally used to pass additional parameters that apply to specific services as described in the section below

Additional Parameters

The table below describes the service codes and the additional parameters required to fulfill the account validation. This list will be updated from time to time depending on the circumstances.

Service Code	Additional Parameter	Description
YAKA	customer_phone	The phone number of the customer. It will receive the confirmation SMS
URA	customer_phone	The phone number of the customer. It will receive the confirmation SMS
GoTV	customer_phone	The phone number of the customer. It will receive the confirmation SMS
DSTV	customer_phone	The phone number of the customer. It will receive the confirmation SMS
NWSC	customer_phone	The phone number of the customer. It will receive the confirmation SMS
	area_code	The choice code value obtained from the choice list API with the list_id being NWSC.Area

After collecting the necessary payment information from your customer, prepare your request payload as demonstrated below.

{
    "merchant_reference": "auto",
    "account_number": "2116789901",
    "service_code": "NWSC",
    "currency": "UGX",
    "amount": 12000,
    "additional_params": {
        "customer_phone": "256704878224",
        "area_code": "NWSC.Area:Kampala"
    }
}

POST https://gwapisdbx.ellypayapp.com/service-payments/validate-account

The request is sent as a JSON body as demonstrated by the sample request below. Sample responses (success and failure) are also shared.

curl -X POST "https://gwapisdbx.ellypayapp.com/service-payments/validate-account" \
   -H 'Content-Type: application/json' \
   -H "x-api-version: 1" \
   -H "public-key: your-public-key" \
   -d '{
        "merchant_reference": "auto",
        "account_number": "2116789901",
        "service_code": "NWSC",
        "currency": "UGX",
        "amount": 12000,
        "additional_params": {
            "customer_phone": "256704878224",
            "area_code": "NWSC.Area:Kampala"
        }
    }'

200: OK - Request processed successfully

{
    "code": 200,
    "status": "success",
    "message": "Request completed successfully",
    "data": {
        "internal_reference": "ELPREFA65BGTFR7NGUXM",
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
        "account_number": "2116789901",
        "request_currency": "UGX",
        "request_amount": 12000,
        "customer_name": "SANDBOX CUSTOMER",
        "transaction_charge": 1000,
        "transaction_amount": 13000,
        "service_name": "NWSC Kampala",
        "balance_due": 2300
    }
}

Response parameters are described below

Parameter	Type	Description
internal_reference	String	The reference generated by the EllyPay platform. This is very critical for the next step of payment confirmation.
merchant_reference	String	The merchant reference as it was sent in the validation request (or auto generated by the system)
account_number	String	The account number that's been validated
request_currency	String	The currency in which the payment is to be done
request_amount	Number	The amount the customer wishes to pay
customer_name	String	The name attached to the account number
transaction_charge	Number	If the service is billable, this parameter will hold the calculated charge for making a payment of the amount, otherwise it will be zero.
transaction_amount	Number	This is the summation of request amount and tranasaction charge. For outbound service payments, this would be the total amount to be deducted from the merchant account wallet
service_name	String	The name of the service for which payment is being made.
balance_due	Number	Some services (e.g. YAKA, NWSC) accrue a balance on the customer accounts. This parameter would hold the value of that balance

400: Bad Request - Request is not formed as expected

{
    "code": 400,
    "status": "error",
    "message": "256752000001 is not a valid MTN Mobile Money Uganda (mtn_ug) phone number",
    "data": {}
}

Step 2: Display details to the customer

We strongly recommend that details returned from the validation process are displayed to the customer especially the name of the accountholder so that there's confirmation before going forward. In some situations e.g. YAKA and NWSC, the balance owed may also be value greater than zero and this needs to be displayed so that the customer is aware.

Step 3: Confirm the payment

When the validation process is successful, the next step is the confirmation of the payment as described in the payment confirmation section. This confirmation expects the internal reference (returned from the validation) as the only parameter in the request. More on this here