> For the complete documentation index, see [llms.txt](https://developers.klasha.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.klasha.com/accepting-payments/payments-api/ussd.md).

# USSD

Follow these steps to accept payment using our USSD API:

* Initiate the USSD Payment
* Steps to Complete Payment
* Check Status

### Coverage

The gateway parameter should be set to anyone of the following currencies below.

<table><thead><tr><th width="231">Country</th><th>Country Code</th><th>Currency</th></tr></thead><tbody><tr><td>Nigeria</td><td>NG</td><td>NGN</td></tr></tbody></table>

### Bank Codes

| **Code** | Bank **Name**       |
| -------- | ------------------- |
| 737      | GTB                 |
| 894      | First Bank          |
| 966      | Zenith Bank         |
| 919      | UBA                 |
| 909      | Stanbic Bank        |
| 5037     | VFD                 |
| 7797     | Rubies (Highstreet) |
| 901      | Access Bank         |
| 822      | Sterling Bank       |
| 7799     | Unity Bank          |
| 7111     | KeyStone Bank       |
| 326      | EcoBank             |
| 945      | Wema Bank           |
| 770      | Fidelity Bank       |
| 329      | FCMB                |
| 745      | Heritage Bank       |
| 826      | Union Bank          |

### Initiate the USSD Payment

> <mark style="color:yellow;">**POST**</mark> - <mark style="color:$primary;">{{env\_url}}/pay/aggregators/{{gateway}}/ussd</mark>

You would need to pass, as header the `x-auth-token`. This can be obtained from your merchant dashboard → Settings → Generate API keys → **Merchant public key.**

**Headers**

| Name         | Value                    |
| ------------ | ------------------------ |
| Content-Type | `application/json`       |
| x-auth-token | Your merchant public key |

**Request Body (encrypted)**

**NB**: Request on this api must be encrypted. See encryption algorithm [**here**](/accepting-payments/payments-api.md#encryption-algorithm)

```json
{
    "message": "encrypted-body"
}
```

**Request Body (plain version)**

> <sup>*\*must be encrypted before sending*</sup>

```json
{
    "tx_ref": "91a4f37c-61f5-48a6-bef6-ec2ef118615b",
    "account_bank": "329",
    "amount": "3448.28",
    "currency": "NGN",
    "email": "test@dev.com",
    "phone_number": "234888888888",
    "sourceCurrency": "NGN",
    "firstName": "tester",
    "lastName": "one",
    "fullname": "tester one"
}
```

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "success"
    "data": {
        "payment_type": "USSD",
        "tx_ref": "91a4f37c-61f5-48a6-bef6-ec2ef118615b",
        "chargeResponseCode": "pending",
        "charged_amount": "3448.28",
        "narration": "USSD Payment",
        "status": "pending",
        "ussdString": "*329*000*3668#"
    },
    "status": "success"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "message": "failed",
    "error": "Bad Request",
    "data": "Check your request and try again"
}
```

{% endtab %}
{% endtabs %}

### Steps to Complete Payment

{% stepper %}
{% step %}
**Retrieve the USSD String**

Once the payment is initiated, a unique `ussdString` specific to the bank will be provided in the response.
{% endstep %}

{% step %}
**Dial the USSD Code**

Use the returned `ussdString` to proceed with the transaction. For example, if the string provided is `*329*000*3668#`, dial it on your phone and press the call button.
{% endstep %}

{% step %}
**Follow On-Screen Instructions**

Complete the transaction by following the prompts displayed during the USSD session.
{% endstep %}
{% endstepper %}

### Check Status

Use the Transaction status API [here](/misc/transaction-status.md) to check the status of the transaction by passing your transaction reference as `tnx_ref` in the request body.