Flow API Integration

The Flow API allows authorized partners to interact with the platform to perform operations such as looking up customers and initiating recharges.

All Flow API requests must be authenticated using an OAuth2 Bearer Token.

---

Authentication

Authentication for the Flow API is a two-step process:

1. Obtain an Access Token: Use your Client ID and Client Secret (provided during onboarding) to request a token.
2. Use the Bearer Token: Include the token in the Authorization header of all subsequent API requests.

1. Obtaining an Access Token

Endpoint: POST /v1/access/partners/token

This endpoint uses HTTP Basic Authentication. Provide your Client ID as the username and your Client Secret as the password.

cURL

curl -X POST https://api.1flow.org/v1/access/partners/token \
     -u "your_client_id:your_client_secret"

Node.js

const axios = require('axios');

const clientId = 'your_client_id';
const clientSecret = 'your_client_secret';
const auth = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

axios.post('https://api.1flow.org/v1/access/partners/token', {}, {
  headers: { 'Authorization': `Basic ${auth}` }
}).then(response => {
  console.log(response.data.access_token);
});

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6IC...",
  "token_type": "Bearer",
  "expires_in": 3600
}

2. Using the Bearer Token

For all other endpoints, include the token in the Authorization header:

Authorization: Bearer <your_access_token>

---

Customer Lookup

Before initiating a recharge, you can look up a customer to verify their details and the devices associated with them.

Endpoint: POST /v1/access/partners/lookup

Request Body

You can look up a customer by phoneNumber or deviceId.

{
  "phoneNumber": "+254712345678"
}

---

Initiate Recharge

To add water credit to a customer's device, use the Initiate Recharge endpoint. This process is asynchronous.

Endpoint: POST /v1/access/partners/recharge

Request Body

Requires either deviceId or cardId, and the amount.

{
  "deviceId": "68753500140920",
  "amount": 100.0
}

Response

The API will return a 202 Accepted status with a rechargeId. You can use this ID to track the status of the recharge.

{
  "success": true,
  "timestamp": 1777885301197,
  "message": "success",
  "data": {
    "id": "98466062-2548-4dca-9ef9-f1b4b09c92dc",
    "serialNumber": "68753500140920",
    "deviceType": "DEVICE",
    "status": "PENDING",
    "amount": 100.5,
    "createdAt": "2026-05-04T09:01:41.197617901Z",
    "customer": {
      "name": "Jane Doe",
      "phoneNumber": "+254712345678"
    }
  }
}

---

Verify Recharge

Check the current status of a recharge using its ID.

Endpoint: GET /v1/access/partners/recharge/{id}

Response

Returns the current status of the recharge (e.g., PENDING, COMPLETED, FAILED).

{
  "success": true,
  "timestamp": 1777890516031,
  "message": "success",
  "data": {
    "id": "800cb2a6-1b5f-4e5d-aba0-22550fab12bb",
    "serialNumber": "68753500140920",
    "deviceType": "DEVICE",
    "status": "COMPLETED",
    "amount": 100.5,
    "currency": "GHS",
    "litres": 20.1,
    "pricePerLitre": 5,
    "balance": 150052,
    "createdAt": "2026-05-04T09:36:30.112536Z",
    "completedAt": "2026-05-04T09:46:28.331923Z",
    "customer": {
      "name": "Jane Doe",
      "phoneNumber": "+254712345678"
    }
  }
}