Rechargely API

Integrate airtime, data bundles, electricity, and bill payments into your application. Explore our REST API with interactive examples.

Base URL

https://rechargely.online/api/wallet/v1

Authentication

All endpoints (except /public/* and /authenticate) require a Bearer token. Include Authorization: Bearer <token> and X-Channel-Id: WEB headers. Tokens expire after 1 hour.

Payment Integration Flow

1POSTAuthenticate

2GETBrowse Categories

3GETList Products

4POSTPre-Auth

5POSTAuthorize

Terminal statuses: COMPLETED, FAILED, CANCELLED

Authentication

POST/authenticate/customers

Authenticate Customer

Authenticate a customer and receive an access token. Tokens expire after 1 hour.

Request Body

usernamestringrequired

The customer's registered email address

passwordstringrequired

The customer's account password

fcmTokenstringrequired

Firebase Cloud Messaging token for push notifications

Response Fields

accessTokenstring

Bearer token to use for all authenticated API requests. Expires after 1 hour.

curl -X POST 'https://rechargely.online/api/wallet/v1/authenticate/customers' \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "user@example.com",
  "password": "yourPassword",
  "fcmToken": "firebase_token_here"
}'

Example Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs..."
}

Products

GET/products/categories Auth Required

List Categories

Returns all available product categories.

Response Fields

idstring

Unique identifier for the category

categorystring

Category name (e.g. "Airtime", "Electricity")

descriptionstring

Human-readable description of the category

logostring

URL to the category logo/icon image

curl -X GET 'https://rechargely.online/api/wallet/v1/products/categories' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'X-Channel-Id: WEB'

Example Response

[
  {
    "id": "cat_001",
    "category": "Airtime",
    "description": "Mobile airtime top-ups",
    "logo": "https://example.com/logos/airtime.png"
  }
]

GET/products/products-list-category/{categoryId} Auth Required

List Products by Category

Returns all products belonging to a specific category.

Path Parameters

categoryIdstringrequired

The unique identifier of a category returned from GET /products/categories

Response Fields

idstring

Unique identifier for the product

namestring

Internal product name

descriptionstring

Human-readable product description

refNamestring

Reference name used for lookups

billFormatstring

Expected format for the bill reference

categorystring

Category this product belongs to

statusstring

Product availability status (ACTIVE, INACTIVE)

billerNamestring

Name of the biller or service provider

currencystring

Currency code (e.g. "USD", "ZWG")

productPricenumber

Fixed price of the product (0 if variable pricing)

productNamestring

Display name shown to end users

providerCodestring

Internal code identifying the upstream provider

pricingTypestring

Pricing model — "FIXED" or "VARIABLE"

productLogoUrlstring

URL to the product logo image

minAmountnumber

Minimum transaction amount allowed

maxAmountnumber

Maximum transaction amount allowed

curl -X GET 'https://rechargely.online/api/wallet/v1/products/products-list-category/{categoryId}' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'X-Channel-Id: WEB'

Example Response

[
  {
    "id": "prod_001",
    "name": "econet_airtime",
    "description": "Econet Airtime",
    "refName": "econet",
    "billFormat": "07XXXXXXXX",
    "category": "Airtime",
    "status": "ACTIVE",
    "billerName": "Econet Wireless",
    "currency": "USD",
    "productPrice": 0,
    "productName": "Econet Airtime",
    "providerCode": "ECONET",
    "pricingType": "VARIABLE",
    "productLogoUrl": "https://example.com/logos/econet.png",
    "minAmount": 0.5,
    "maxAmount": 500
  }
]

GET/products/providers/{name} Auth Required

List Providers

Returns available service providers for a given product reference name.

Path Parameters

namestringrequired

The product reference name (e.g. refName from a product)

Response Fields

providerNamestring

Display name of the provider

curl -X GET 'https://rechargely.online/api/wallet/v1/products/providers/{name}' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'X-Channel-Id: WEB'

Example Response

[
  {
    "providerName": "Econet Wireless"
  },
  {
    "providerName": "NetOne"
  }
]

Search

GET/public/products/search

Search Products

Search for products by keyword. No authentication required.

Query Parameters

querystringrequired

Search keyword to match against product names and descriptions

curl -X GET 'https://rechargely.online/api/wallet/v1/public/products/search?query=airtime'

Example Response

[
  {
    "id": "prod_001",
    "name": "econet_airtime",
    "description": "Econet Airtime",
    "refName": "econet",
    "billFormat": "07XXXXXXXX",
    "category": "Airtime",
    "status": "ACTIVE",
    "billerName": "Econet Wireless",
    "currency": "USD",
    "productPrice": 0,
    "productName": "Econet Airtime",
    "providerCode": "ECONET",
    "pricingType": "VARIABLE",
    "productLogoUrl": "https://example.com/logos/econet.png",
    "minAmount": 0.5,
    "maxAmount": 500
  }
]

Transactions

POST/v1/transactions/bill-payment/pre-auth Auth Required

Initiate Payment (Pre-Auth)

Initiate a new bill payment transaction by creating a pre-authorization request.

Request Body

amountnumberrequired

Payment amount in the product's currency

productIdnumberrequired

The id of the product being purchased

requestIdstringrequired

Client-generated unique identifier for idempotency

billReferencestringrequired

The account/reference number being paid (e.g. phone number, meter number)

customerMobilestringrequired

Customer's mobile number

additionalDataobjectrequired

Additional key-value pairs for the transaction

Response Fields

responseCodestring

Response status code from the payment gateway

responseMessagestring

Human-readable response message

preAuthTokenstring

Token required to authorize the payment in the next step

requestIdstring

Echoed back request identifier

statusstringnullable

Transaction status: PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED

curl -X POST 'https://rechargely.online/api/wallet/v1/transactions/bill-payment/pre-auth' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'X-Channel-Id: WEB' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 0,
  "productId": 0,
  "requestId": "string",
  "billReference": "string",
  "customerMobile": "string",
  "additionalData": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}'

Example Response

{
  "responseCode": "200",
  "responseMessage": "Payment initiated successfully",
  "preAuthToken": "preauth_abc123",
  "requestId": "string",
  "status": "PENDING"
}

POST/v1/transactions/bill-payment/auth Auth Required

Authorize Payment

Authorize a previously initiated payment. This is the step where the actual charge occurs.

Request Body

preAuthTokenstringrequired

The preAuthToken received from the pre-auth response

requestIdstringrequired

The same requestId used during initiation

Response Fields

responseCodestring

Response status code from the payment gateway

responseMessagestring

Human-readable response message

transactionReferencestring

Unique reference for the completed transaction

statusstring

Authorization result status

requestIdstring

Echoed back request identifier

curl -X POST 'https://rechargely.online/api/wallet/v1/transactions/bill-payment/auth' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'X-Channel-Id: WEB' \
  -H 'Content-Type: application/json' \
  -d '{
  "preAuthToken": "string",
  "requestId": "string"
}'

Example Response

{
  "responseCode": "200",
  "responseMessage": "Payment authorized successfully",
  "transactionReference": "TXN-2026-00001234",
  "status": "COMPLETED",
  "requestId": "string"
}

Error Handling

API errors return standard HTTP status codes with a JSON body:

{
  "message": "Human-readable error description"
}

400Bad request — invalid or missing fields

401Unauthorized — token is missing, invalid, or expired

403Forbidden — insufficient permissions

404Not found — resource does not exist

409Conflict — duplicate resource (e.g. duplicate requestId)

422Validation error — fields are present but invalid

500Internal server error — contact support

502Bad gateway — upstream service temporarily unavailable

503Service unavailable — try again later

504Gateway timeout — try again later

Rechargely API v1 · Need help? Contact support