API Reference

Complete reference documentation for all FLUID Network API endpoints.

Base URLs

Sandbox Environment

https://sandbox-api.fluid-network.com/api/v1/payment-providers/

Production Environment

https://api.fluid-network.com/api/v1/payment-providers/

API Version

Current version: v1

The API version is included in the URL path. All endpoints are namespaced under /api/v1/payment-providers/.

Request Format

Headers

All API requests require these headers:

Header	Required	Description
Authorization	Yes	Bearer token with your API key
Content-Type	Yes	Must be application/json
Accept	Yes	Must be application/json

Example Request

curl -X GET \
  https://api.fluid-network.com/api/v1/payment-providers/banks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Response Format

All API responses follow a consistent JSON structure:

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2025-11-12T14:30:00Z",
    "request_id": "req_abc123",
    "api_version": "v1"
  }
}

Error Response

{
  "success": false,
  "error": "Error message",
  "details": ["Additional error details"]
}

HTTP Status Codes

Status Code	Description
200 OK	Request successful
400 Bad Request	Invalid request parameters
401 Unauthorized	Invalid or missing API key
403 Forbidden	API key lacks permission
404 Not Found	Resource not found
422 Unprocessable Entity	Validation error
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error

Available Endpoints

Payment Providers API

Endpoints for payment providers (merchants, payment platforms) to initiate and manage transactions.

Banks

Endpoints for retrieving bank information and customer account lookups.

Endpoint	Method	Description
List Banks	GET	Get all available banks
Get Bank	GET	Get specific bank details
Lookup Customer	GET	Find customer's linked banks

Debit Requests

Endpoints for initiating and managing debit transactions.

Endpoint	Method	Description
Create Charge	POST	Initiate a debit request
Get Status	GET	Check transaction status

Banks API

Endpoints for banks to fetch and update transaction statuses.

INFO

These endpoints are for banks only. They use a different authentication token and base URL: /api/v1/banks/

Endpoint	Method	Description
List Transactions	GET	Fetch pending transactions for a customer
Update Transaction	POST	Update transaction status after approval

Webhooks

Real-time notifications for transaction events.

Topic	Description
Overview	Webhook concepts and setup
Event Types	Available webhook events
Signature Verification	Verify webhook authenticity

Rate Limiting

API requests are rate-limited to ensure fair usage:

Environment	Requests per Minute	Burst Limit
Sandbox	30	50
Production	60	100

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1699876543

Learn more in the Rate Limiting Guide.

Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer YOUR_API_KEY

For enhanced security, you can enable HMAC authentication:

• Bearer Token Authentication
• HMAC Authentication
• IP Whitelisting

Pagination

Endpoints that return lists support pagination using query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	20	Items per page (max 100)

Example:

curl -X GET \
  "https://api.fluid-network.com/api/v1/payment-providers/banks?page=2&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes pagination metadata:

{
  "success": true,
  "data": [...],
  "meta": {
    "current_page": 2,
    "per_page": 50,
    "total_pages": 5,
    "total_count": 234
  }
}

Error Handling

All errors follow a consistent format. See the Error Handling Guide for details.

Common Error Codes

Code	Description	Resolution
1001	Invalid API key	Check your API key is correct
1002	API key disabled	Contact support
2001	Invalid phone number	Use E.164 format (+233...)
2002	Bank not found	Check bank identifier
3001	Insufficient funds	Customer needs to fund account
3002	Transaction declined	Customer rejected transaction

Complete list: Error Codes Reference

Idempotency

Debit request endpoints support idempotency using the partner_reference field. Sending the same partner_reference multiple times will return the same transaction.

Learn more in the Idempotency Guide.

Testing

Use the Sandbox environment for testing:

• Sandbox URL: https://sandbox-api.fluid-network.com
• Test API keys: Prefixed with test_sk_
• Test data: Test phone numbers and scenarios

See the Testing Guide for comprehensive testing strategies.

Need Help?

• 📖 Integration Guides
• 🚀 Quickstart Tutorial
• 💬 Contact Support
• 📝 Changelog