Payment Confirmation

After the account validation has successfully responded with the account details. You can proceed to confirm the payment for the service

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: Setup the payment confirmation request

The table below describes the request parameters that are used for the payment confirmation request.

Parameter	Type	Required	Description
internal_reference	String	true	The internal reference returned as part of the validation response
secret_code	String	false	This one is a special parameter that applies to Airtel Money Withdraw transactions. The customer secret code should be Base64 encoded before sending the API request.

Prepare your request payload as demonstrated below.

{
    "internal_reference": "ELPREFQ9ULSYC7KAASWJ"
}

POST https://gwapisdbx.ellypayapp.com/service-payments/process-payment

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

curl -X POST "https://gwapisdbx.ellypayapp.com/service-payments/process-payment" \
   -H 'Content-Type: application/json' \
   -H "x-api-version: 1" \
   -H "public-key: your-public-key" \
   -d '{
        "internal_reference": "ELPREFQ9ULSYC7KAASWJ"
    }'

200: OK - Request processed successfully

{
    "code": 202,
    "status": "accepted",
    "message": "Request Accepted",
    "data": {
        "internal_reference": "ELPREFA65BGTFR7NGUXM",
        "merchant_reference": "MCTREFT2WMNWZ23SBN6Y"
    }
}

400: Bad Request - Request is not formed as expected

{
    "code": 400,
    "status": "error",
    "message": "Unknown internal reference",
    "data": {}
}

Step 2: Handle final status notification

Every merchant account is expected to have configured a callback/webhook URL for service payments. For all transactions that transition to the final state (COMPLETED or FAILED), a JSON POST request will be made to the callback URL. Sample callback payloads (request bodies) are shared below. Be sure to check out Handling Notifications to see how you should verify the signature(s) in the request headers and how to respond.

Successful Service Payment

{
    "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": {}
    }
}

In some situations, the payload.additional_details parameter will hold extra details about the payment e.g. the YAKA token etc. The table below decribes some of the expected parameters in the additional_details object.

Parameter	Type	Description
token	String	The YAKA token. Only returned on YAKA payments
units	Number	The total units purchased. Usually returned on YAKA payments
receipt_number	String	The payment receipt. Usually returned on utility or tax payments
description	String	Description of the payment. This usually applies to all service payments
debt_recovery	String	Usually returns on YAKA payments
fuel	String	Usually returns on YAKA payments
inflation	String	Usually returns on YAKA payments
tax	String	Usually returns on YAKA payments
customer_phone	String	Usually returns on utility, tax and digital TV payments

Failed Service Payment

{
    "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": {}
    }
}