Paybills Africa Partner API: Floating Partners

Parter API integration guide

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.

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.

Paybills.Africa floating partner sequence diagram

Get your API keys, send an email request to [email protected]

Authentication

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

Gets Auth token

POST https://accounts.brij.africa/api/v1/connect/token

Use x-www-form-urlencoded body to obtain a bearer token

Request/Response Body

Request

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

200: OK success

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

Retrieve Countries

To retrieve countries call this endpoint with a bearer auth token

GET https://api.paybills.africa/api/v1/partner/countries

200: OK success

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

}

400: Bad Request

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

Retrieve Categories

GET https://api.paybills.africa/api/v1/partner/categories

200: OK success

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

400: Bad Request

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

Retrieve Merchants

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

POST https://api.paybills.africa/api/v1/partner/merchants

Request/Response Body

Request

{
  "countryId": "string" | null,
  "categoryId": "string" | null,
  "index": 0,
  "pageSize": 0
}

Response: 200 OK

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

Response: 400 Bad Request

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

Customer Lookup

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

POST https://api.paybills.africa/api/v1/partner/lookup-customer

Request/Response body

Request

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

Response: 200 OK

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

Response: 400 Bad Request

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

Create Order

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

POST https://api.paybills.africa/api/v1/partner/funded/create-order

Request/Response body

Request

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

Response: 200 OK

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

Response: 400 Bad Request

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

Complete Order

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

POST https://api.paybills.africa/api/v1/partner/funded/complete-order

Request

Request

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

Response: 200 OK

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

Response: 400 Bad Request

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

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.

Callback Json Payload

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