# Paybills Africa Partner API: Non-floating Partners

The following documentation describes the Paybills Africa cross-border bill payment partner APIs for **Non-Floating partners.**

Non-floating partners will not need to have a float account on our end but will debit their users and credit Brij in a collection account for settlement. The API is **trustless**, which means that confirmation of payment collection by a partner will need to be confirmed through a transaction verification API call before the bill payment is completed.

The flow diagram below summarizes the bill payment process using this API. The countries and categories API can be called periodically to GET an updated list of available countries and categories.

<figure><picture><source srcset="/files/ulcYwJPIKraaepgSWA7K" media="(prefers-color-scheme: dark)"><img src="/files/fjmdYWsAVmWB7i0ptV11" alt=""></picture><figcaption><p>Paybills.Africa Non-Floating partners sequence diagram</p></figcaption></figure>

{% hint style="info" %}
Get your API keys, send an email request to <support@paybills.africa>
{% endhint %}

## Authentication

To obtain a bearer token send the following fields to the token endpoint

## Gets Auth token

<mark style="color:green;">`POST`</mark> `https://accounts.brij.africa/api/v1/connect/token`

Use **x-www-form-urlencoded body** to obtain a  bearer token &#x20;

#### Request/Response Body

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

```
  { 
    "username": "<your-username>",
    "expires_in": "<your-client-id>",
    "token_type": "<your-password",
  }
```

{% endtab %}

{% tab title="200: OK success" %}

```
  { 
    "access_token": "string",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "string" 
  }
```

{% endtab %}
{% endtabs %}

## Retrieve Countries

To retrieve countries call this endpoint with a bearer auth token

<mark style="color:blue;">`GET`</mark> `https://api.paybills.africa/api/v1/partner/countries`

{% tabs %}
{% tab title="200: OK success" %}

```json
{
  "result": [
    {
      "id": "string",
      "name": "string",
      "currency": "string"
    }
  ],
  "message": "string",
  "code": 1,
  "errors": [
       "string"
    ]

}
```

{% endtab %}
{% endtabs %}

## Retrieve Partner Categories

<mark style="color:blue;">`GET`</mark> `https://api.paybills.africa/api/v1/partner/categories`

{% tabs %}
{% tab title="200: OK success" %}

```json
{
  "result": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "message": "string",
  "code": 1,
  "errors": ["string"]
}
```

{% endtab %}
{% endtabs %}

## Retrieve Merchants

One can retrieve merchant by specifying category, country or both.

<mark style="color:green;">`POST`</mark> `https://api.paybills.africa/api/v1/partner/merchants`

#### Request/Response Body

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

```json
{
  "countryId": "string",
  "categoryId": "string",
  "index": 0,
  "pageSize": 10
}
```

{% endtab %}

{% tab title="Response: 200 OK" %}

```json
{
  "result": [
    {
      "id": "string",
      "name": "string",
      "countryName": "string",
      "categoryName": "string",
      "merchantServices": [
        {
          "id": "string",
          "serviceName": "string",
          "needsLookup": true
        }
      ]
    }
  ],
  "message": "string",
  "code": 1,
  "errors": [
    "string"
  ]
}
```

{% endtab %}
{% endtabs %}

## Customer Lookup

<mark style="color:green;">`POST`</mark> `https://api.paybills.africa/api/v1/partner/lookup-customer`

#### Request/Response body

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

```json
{
  "reference": "string",
  "merchantId": "string",
  "merchantServiceId": "string"
}

```

{% endtab %}

{% tab title="Response: 200 OK" %}

```json
{
  "result": {
    "name": "string",
    "amount": 0,
    "amountType": 0,
    "additionalData": "string"
  },
  "message": "string",
  "code": 1,
  "errors": [
    "string"
  ]
}
```

{% endtab %}

{% tab title="Response: 400 Bad Request" %}

```json
{
  "result":null,
  "message": "error message",
  "code": 2 | 3,
  "errors": ["validation","error","messages"]
}
```

{% endtab %}

{% tab title="Response: 404 Not Found" %}

```json
{
  "result":null,
  "message": "message",
  "code":4,
  "errors": []
}
```

{% endtab %}
{% endtabs %}

## Create Order

<mark style="color:green;">`POST`</mark> `https://api.paybills.africa/api/v1/partner/create-order`

#### Request/Response Body

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

```json
{
  "payerName": "string",
  "payerPhone": "string",
  "merchantId": "string",
  "merchantServiceId": "string", 
  "billAmount": 0,
  "billCurrency": "string", // ISO 4217
  "sourceCurrency": "string", // ISO 4217
  "billReference": "string",
  "narration": "string"
}
```

{% endtab %}

{% tab title="200: OK success" %}

```json
{
    "result": [
         {
	 "invoiceId": "string",
              "billCurrency": "string",
              "sourceCurrency": "string",
              "exchangeRate": decimal,
              "merchantName": "string",
              "billAmount":  decimal,
              "sourceAmount":  decimal,
               "fee": decimal
          }
     ],
     "message": "string",
     "code": 1,
     "errors": [
          "string"
       ]
}

```

{% endtab %}

{% tab title="400: Bad Request" %}

```json
{
  "result":null,
  "message": "error message",
  "code": 2 | 3,
  "errors": ["validation","error","messages"]
}
```

{% endtab %}
{% endtabs %}

## Partner Callback to Paybills Africa

After debiting your user, a callback is to be sent to the following endpoint&#x20;

### Callback to Paybills Africa

<mark style="color:green;">`POST`</mark> `https://api.paybills.africa/api/v1/partner/order-callback`

#### Request Body

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

```json
{
  "invoiceId": "string",
  "partnerReference": "string",
  "amount": 0,
  "status": "string"
}
```

{% endtab %}

{% tab title="Response: 200 OK" %}

```json
{
  "result": {
    "status": "Accepted"
  },
  "message": "success",
  "code": 1,
  "errors": []
}
```

{% endtab %}

{% tab title="Response: 400 Bad Request" %}

```json
{
  "result":null,
  "message": "error message",
  "code": 2,
  "errors": []
}
```

{% endtab %}
{% endtabs %}

### Bill Payment Processing Callback

After verifying the partner transaction the bill payment process will proceed and Paybills.Africa will notify the partner system of the processing status by sending a JSON payload to the partner’s callback URL.&#x20;

The information sent will allow the partner to display the status and third-party references to their user or refund money in the case of a failed bill payment.

The data object may be null or contain additional metadata.

{% code title="Callback Json Payload" %}

```json
{
     "invoiceId": "string", 
     "thirdPartyReference": “string”,// transaction reference provided by third party system
     "status": “Completed or Failed”,
     "data":{} | null
 }

```

{% endcode %}


---

# 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://docs.brij.africa/paybills-africa-partner-api-non-floating-partners.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.