# Account Validation

{% hint style="info" %}
We recommend checking out the [Getting Started](/service-payments/getting-started.md) section to understand the basics of service payments first and the general workflow. This guide assumes that you have read that
{% endhint %}

## 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.

<table><thead><tr><th width="197">Parameter</th><th width="93">Type</th><th width="98">Required</th><th>Description</th></tr></thead><tbody><tr><td>merchant_reference</td><td>String</td><td>true</td><td>The unique reference for this request. It must be at least 8 characters long. You can pass the value as <strong>auto</strong> and the API will generate a reference on your behalf</td></tr><tr><td>account_number</td><td>String</td><td>true</td><td>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</td></tr><tr><td>service_code</td><td>String</td><td>true</td><td>The unique service code. For services with price/package lists, use the item code from the <a href="/pages/Tqfh8Fn8v8I2WQnWQRXh">packages list</a> otherwise use the code from the main <a href="/pages/xchW5QFIpbPqLU8Gqn1I">service list</a></td></tr><tr><td>currency</td><td>String</td><td>true</td><td>The 3-character ISO currency code for the request currency</td></tr><tr><td>amount</td><td>Number</td><td>true</td><td>The amount to be transferred</td></tr><tr><td>additional_params</td><td>Object</td><td>false</td><td>This parameter normally used to pass additional parameters that apply to specific services as described in the section below</td></tr></tbody></table>

### 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.

<table><thead><tr><th width="145">Service Code</th><th width="190">Additional Parameter</th><th>Description</th></tr></thead><tbody><tr><td>YAKA</td><td>customer_phone</td><td>The phone number of the customer. It will receive the confirmation SMS</td></tr><tr><td>URA</td><td>customer_phone</td><td>The phone number of the customer. It will receive the confirmation SMS</td></tr><tr><td>GoTV</td><td>customer_phone</td><td>The phone number of the customer. It will receive the confirmation SMS</td></tr><tr><td>DSTV</td><td>customer_phone</td><td>The phone number of the customer. It will receive the confirmation SMS</td></tr><tr><td>NWSC</td><td>customer_phone</td><td>The phone number of the customer. It will receive the confirmation SMS</td></tr><tr><td></td><td>area_code</td><td>The choice code value obtained from the choice list <a href="/pages/5e3qvKKuGSczK5bLQo2w">API</a> with the list_id being NWSC.Area</td></tr></tbody></table>

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

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

<mark style="color:green;">`POST`</mark> `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.

```powershell
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"
        }
    }'
```

{% tabs %}
{% tab title="200: OK - Request processed successfully" %}

```json
{
    "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

<table><thead><tr><th width="202">Parameter</th><th width="107">Type</th><th>Description</th></tr></thead><tbody><tr><td>internal_reference</td><td>String</td><td>The reference generated by the EllyPay platform. This is very critical for the next step of payment confirmation.</td></tr><tr><td>merchant_reference</td><td>String</td><td>The merchant reference as it was sent in the validation request (or auto generated by the system)</td></tr><tr><td>account_number</td><td>String</td><td>The account number that's been validated</td></tr><tr><td>request_currency</td><td>String</td><td>The currency in which the payment is to be done</td></tr><tr><td>request_amount</td><td>Number</td><td>The amount the customer wishes to pay</td></tr><tr><td>customer_name</td><td>String</td><td>The name attached to the account number</td></tr><tr><td>transaction_charge</td><td>Number</td><td>If the service is billable, this parameter will hold the calculated charge for making a payment of the amount, otherwise it will be zero.</td></tr><tr><td>transaction_amount</td><td>Number</td><td>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</td></tr><tr><td>service_name</td><td>String</td><td>The name of the service for which payment is being made.</td></tr><tr><td>balance_due</td><td>Number</td><td>Some services (e.g. YAKA, NWSC) accrue a balance on the customer accounts. This parameter would hold the value of that balance</td></tr></tbody></table>
{% endtab %}

{% tab title="400: Bad Request - Request is not formed as expected" %}

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

{% endtab %}
{% endtabs %}

## Step 2: Display details to the customer

{% hint style="info" %}
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.
{% endhint %}

## 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](/service-payments/payment-confirmation.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.ellypayapp.com/service-payments/account-validation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.