Getting Started

Service payments is a term EllyPay uses to describe outbound (mostly) payments from your merchant account to supported service accounts e.g. UMEME, URA, mobile services etc.

The API supports payments/transactions for a number of service categories e.g. Mobile Money, Internet, Tax, Utilities, Airtime, PayTV and other methods may be supported along the way. The API enables you to send payments via a simple, secure process that requires only the account information of the recipients. This section will describe the process flow for service payment as well as the other supporting data endpoints. However, every service payment will follow the steps described below, in the order of occurrence.

Prerequisites

Before service payments can start,

1. The merchant needs to have an approved merchant account on the live platform. This is only achieved after the go-live requirements are met (being on sandbox and clearing the UAT tests).

2. The service options required by the merchant need to be configured on the designated merchant account. The support teams will be available to assist with this.

3. The merchant is expected to have configured the service payment notification URL on the merchant account profile. The notification URL will receive webhook/callback requests when the payment is successful/failed.

4. The merchant needs to avail the funds for service payments. This can be achieved by requesting transfer of funds collected or deposited prior as described in the Availing Service Payment Funds section. This is a requirement for outbound service payments. For those that are inbound (increase merchant account balance) e.g. the Mobile Money Withdraw services, this step may not be a requirement so it depends on the merchant's needs.

Step 1: Account Validation Request

This is a requirement prior to the actual payment request. The purpose of this step is to get confirmation of the service account name as well as other details as the service may deem necessary e.g. PRN amount for URA or the balance for NWSC and UMEME YAKA.

The merchant will form the validation request payload (based on the selected service) and send it to the API for processing. If there are any errors with the parameters, these would be communicated immediately in the response otherwise the API would respond with the details of the account number. Take the following the airtime validation request and a sample response.

{
    "merchant_reference": "auto",
    "account_number": "2567770123456",
    "service_code": "MTNAirtime",
    "currency": "UGX",
    "amount": 10000
}

/*sample response would be something like the following*/
{
    "code": 200,
    "status": "success",
    "message": "Request completed successfully",
    "data": {
        "internal_reference": "ELPREFA65BGTFR7NGUXM",
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y",
        "account_number": "2567770123456",
        "request_currency": "UGX",
        "request_amount": 10000,
        "customer_name": "SANDBOX CUSTOMER",
        "transaction_charge": 0,
        "transaction_amount": 10000,
        "service_name": "MTN Airtime",
        "balance_due": 0
    }
}

Step 2: Payment Confirmation Request

After the account validation has successfully responded with the account details, you can proceed to confirm the service payment. In the validation response, the value returned in the data.internal_reference parameter will be critical in the confirmation. It's the only parameter that will be sent for the payment confirmation request as demonstrated below.

The API will respond with an acknowledgement and then go ahead to process the payment in the background, sending a notification for the final status when processing is complete/failed.

{
    "internal_reference": "ELPREFA65BGTFR7NGUXM"
}

/*sample acknowledgement would be something like the following*/
{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "ELPREFA65BGTFR7NGUXM",
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y"
    }
}

Step 3: Final Status Notification

This is the notification that communicates the very final status of the transaction, and this would mark the close of the transaction process. Sample completed and failed transaction callbacks/notifications shared below.

/*sample completed transaction callback*/
{
    "event": "payment.completed",
    "payload": {
        "merchant_reference": "MCTPAY7JAKLM2CGHUAUK",
        "internal_reference": "ELPREFAJJXPPALHUWKFY",
        "transaction_type": "SERVICE_PAYMENT",
        "request_currency": "UGX",
        "request_amount": 1000,
        "transaction_status": "COMPLETED",
        "account_number": "256772007180",
        "transaction_charge": 0,
        "transaction_amount": 1000,
        "customer_name": "SANDBOX CUSTOMER",
        "service_name": "MTN Airtime",
        "status_message": "Transaction Completed Successfully",
        "additional_details": {}
    }
}

/*sample failed transaction callback*/
{
    "event": "payment.failed",
    "payload": {
        "merchant_reference": "MCTPAYWQXZML3EQR7TKT",
        "internal_reference": "ELPREFNWSN5RFEBWHHWK",
        "transaction_type": "SERVICE_PAYMENT",
        "request_currency": "UGX",
        "request_amount": 1000,
        "transaction_status": "FAILED",
        "account_number": "256772000004",
        "transaction_charge": 0,
        "transaction_amount": 0,
        "customer_name": "SANDBOX CUSTOMER",
        "service_name": "MTN Airtime",
        "status_message": "Insufficient funds to complete transaction",
        "additional_details": {}
    }
}

Handling of transaction charges

There's a charge attached when paying for some of the services (the ones in this list and the parameter is_billable is true). The amount plus the calculated charge would be deducted for the merchant account's service payment wallet and therefore the wallet should have sufficient funds to support the transaction.