# Paybills Africa Partner API: Floating Partners

## Welcome to the Partner API

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

Floating partners will need to have a float account with Brij, accessible and pre-funded via the [merchant portal](https://merchant.brij.money/auth/login). 

The diagram below outlines a sequence of interactions among the Partners/Customers in the Paybills.Africa platform, Merchant Portal in the context of bill payment processing. 

<figure><picture><source srcset="https://1159212615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsZTTfit0BGyoonfK4sRi%2Fuploads%2Fnsoy1PP3LctEplR2cLEd%2Fpartner-api-floating-sequence-dark.svg?alt=media&#x26;token=7757e28d-86ac-416c-b560-6128fcbfaeea" media="(prefers-color-scheme: dark)"><img src="https://1159212615-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsZTTfit0BGyoonfK4sRi%2Fuploads%2FVsMLnYdb6zRw4R0BCNrD%2Fpartner-api-floating-sequence.svg?alt=media&#x26;token=02fd2fec-7e99-4d4e-9cd8-19ff3ba14ed0" alt=""></picture><figcaption><p>Paybills.Africa floating partner 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 %}

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

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

{% endtab %}
{% endtabs %}

## Retrieve 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 %}

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

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

{% 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" | null,
  "categoryId": "string" | null,
  "index": 0,
  "pageSize": 0
}
```

{% 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 %}

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

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

{% endtab %}
{% endtabs %}

## Customer Lookup

For merchants that have services, you can retrieve customer information if the merchant's service supports lookup ( needsLookup=true).

<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": "A string with error message",
  "code": 2 | 3,
  "errors": ["validation","error","messages"]
}
```

{% endtab %}
{% endtabs %}

## Create Order

Call this API to present invoice information to the user and collect funds from them.

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

#### Request/Response body

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

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

{% endtab %}

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

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

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Complete Order

Call this API once you have collected funds from your end user.

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

#### Request

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

```json
{
  "invoiceId": "string",
  "callbackUrl": "string"
}
```

{% endtab %}

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

```json
{
  "result": {
    "invoiceId": "string",
    "isProcessing": boolean
  },
  "message": "success",
  "code": 1,
  "errors": []
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

### Bill Payment Processing Callback

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 in form of key value pairs that should be extracted and information forwarded to your customers.

In case the status is Failed, an **automatic reversal** of funds is done on your Merchant Portal Wallet.

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

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

```

{% endcode %}