# Getting Started 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](/knowledge-base/availing-service-payment-funds.md) 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. ## Workflow Overview Study this diagram below to understand the customer journey workflow and how the API request/response happens ```mermaid sequenceDiagram actor Customer participant Merchant Portal participant EllyPay Gateway participant Service Provider Customer->>Merchant Portal: Initiates account validation request Merchant Portal->>EllyPay Gateway: POST /service-payments/validate-account (Account validation) EllyPay Gateway-->>Merchant Portal: HTTP 200 response with account details Merchant Portal->>EllyPay Gateway: POST /service-payments/process-payment (Payment confirmation) EllyPay Gateway-->>Merchant Portal: 202 Accepted EllyPay Gateway->>Service Provider: Payment request for amount Service Provider->>Customer: Effect service payment for customer and send SMS Service Provider->>EllyPay Gateway: Notification of transaction completion EllyPay Gateway->>Merchant Portal: Merchant callback notification Merchant Portal->>Customer: Display success message ``` ## 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. ```json { "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. ```json { "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. ```json /*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": {} } } ``` {% hint style="info" %} **Handling of transaction charges** There's a charge attached when paying for some of the services (the ones in [this](/service-payments/services-list.md) 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. {% endhint %} --- # 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/getting-started.md?ask= ``` 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.