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;

Prepare Validation Details

Send a JSON POST request to the API endpoint below;

POST https://sandbox.ellypayapp.com/merchant/validate-account

Some validation requests require more parameters than others. This depends on the product being purchased. Study the section below carefully to understand what is required in the different scenarios.

Request

Request Body

Parameter	Type	Description	Required
agent_reference	string	The unique reference generated from your system. The reference should be 4 to 30 characters in length	YES
account_number	string	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	YES
product_code	string	The unique product code. For products with price lists, use the item code from the price-list otherwise use the code from the main product list	YES
amount	float	The transaction amount. This parameter can be omitted for Airtel Money Withdraw and URA PRN Payments.	YES
extra_params	object	This parameter normally used to pass data that applies to specific products as described in the section below	NO

Extra Parameters

The table below describes the product codes and the extra parameters required to fulfill the account validation.

Product Code	Extra Parameter(s)	Description
YAKA	customer_phone	The phone number of the customer. It will receive the confirmation SMS
UMEMEPp	customer_phone	The phone number of the customer. It will receive the confirmation SMS
TUGENDE	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
KCCA	customer_phone	The phone number of the customer. It will receive the confirmation SMS
STARTIMES	customer_phone	The phone number of the customer. It will receive the confirmation SMS
ZUKU	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
AZAM	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_id	The choice id value obtained from the choice list API with the list_id being NWSC.Area

If you can obtain the customer email, it can be passed with the parameter name customer_email as part of the extra parameters.

Response

Response Body

Parameter	Type	Description
account_number	string	The account number as shared in the request
customer_name	string	The name of the account holder
amount	float	The validated transaction amount
surcharge	float	The amount EllyPay will charge for this transaction if applicable
balance_due	float	The account outstanding balance e.g. on Yaka or NWSC
amount_to_accept	float	The total amount of money the customer should pay for the transaction to proceed successfully
display_balance	boolean	Whether to display the outstanding balance to the customer before the transaction is confirmed.
product_name	string	The full name of the product
validation_reference	string	The unique EllyPay reference for this validation. Ensure you store this value as it is a requirement to process the transaction.

Sample Request

{
	"agent_reference": "YRWWBKLKM84KACI",
	"account_number": "04247431549",
	"product_code": "YAKA",
	"amount": 10000,
	"extra_params": {
		"customer_phone": "0704878224"
	}
}

Sample Response (OK)

{
    "code": 200,
    "status": "success",
    "message": "Request completed successfully.",
    "data": {
        "account_number": "04247431549",
        "customer_name": "KASHIJA, ELIA",
        "amount": 10000,
        "surcharge": 1000,
        "balance_due": 85,
        "amount_to_accept": 11000,
        "display_balance": true,
        "product_name": "UMEME PrePaid (Yaka)",
        "validation_reference": "ELPREFYRWWKVZKMAU1YXC"
    }
}

Sample Response (Error)

{
    "code": 422,
    "status": "error",
    "message": "Invalid Account Number",
    "data": {}
}