# Payment Confirmation

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

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

<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>internal_reference</td><td>String</td><td>true</td><td>The internal reference returned as part of the validation response</td></tr><tr><td>secret_code</td><td>String</td><td>false</td><td>This one is a special parameter that applies to Airtel Money Withdraw transactions. <em><strong>The customer secret code should be Base64 encoded before sending the API request</strong></em>.</td></tr></tbody></table>

Prepare your request payload as demonstrated below.

```json
{
    "internal_reference": "ELPREFQ9ULSYC7KAASWJ"
}
```

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

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

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

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

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## 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](/utility-functions/handling-notifications-callbacks.md) to see how you should verify the signature(s) in the request headers and how to respond.

{% tabs %}
{% tab title="Successful Service Payment" %}

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

<table><thead><tr><th width="171">Parameter</th><th width="101">Type</th><th>Description</th></tr></thead><tbody><tr><td>token</td><td>String</td><td>The YAKA token. Only returned on YAKA payments</td></tr><tr><td>units</td><td>Number</td><td>The total units purchased. Usually returned on YAKA payments</td></tr><tr><td>receipt_number</td><td>String</td><td>The payment receipt. Usually returned on utility or tax payments</td></tr><tr><td>description</td><td>String</td><td>Description of the payment. This usually applies to all service payments</td></tr><tr><td>debt_recovery</td><td>String</td><td>Usually returns on YAKA payments</td></tr><tr><td>fuel</td><td>String</td><td>Usually returns on YAKA payments</td></tr><tr><td>inflation</td><td>String</td><td>Usually returns on YAKA payments</td></tr><tr><td>tax</td><td>String</td><td>Usually returns on YAKA payments</td></tr><tr><td>customer_phone</td><td>String</td><td>Usually returns on utility, tax and digital TV payments</td></tr></tbody></table>
{% endtab %}

{% tab title="Failed Service Payment" %}

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

{% endtab %}
{% endtabs %}


---

# 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/payment-confirmation.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.