Paybills Africa Partner API: Non-floating Partners

Parter API integration guide

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.

Paybills.Africa Non-Floating partners 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"
    ]

}

Retrieve Partner Categories

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

200: OK success

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

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",
  "categoryId": "string",
  "index": 0,
  "pageSize": 10
}

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"
  ]
}

Customer Lookup

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

Response: 404 Not Found

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

Create Order

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

Request/Response Body

Request

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

200: OK success

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

400: Bad Request

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

Partner Callback to Paybills Africa

After debiting your user, a callback is to be sent to the following endpoint

Callback to Paybills Africa

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

Request Body

Request

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

Response: 200 OK

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

Response: 400 Bad Request

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

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.

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.

Callback Json Payload

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