Appearance

Quickstart ​

Get started with the FLUID Network API in under 5 minutes. This guide walks you through making your first API call to list available banks.

Prerequisites ​

Before you begin, make sure you have:

  • A FLUID Network API key (Get one here)
  • A way to make HTTP requests (cURL, Postman, or your favorite programming language)
  • Understanding of Authentication basics

Note: This quickstart uses the Sandbox environment. All transactions are simulated and no real money is involved.

Step 1: Set Up Your Environment ​

First, save your Sandbox API key as an environment variable.

Linux/macOS:

bash
export FLUID_API_KEY="test_sk_your_sandbox_key_here"

Windows PowerShell:

powershell
$env:FLUID_API_KEY="test_sk_your_sandbox_key_here"

Windows CMD:

cmd
set FLUID_API_KEY=test_sk_your_sandbox_key_here

Step 2: Make Your First API Call ​

Let's fetch the list of available banks in the FLUID Network using a GET request to the banks endpoint.

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

Implementation Notes:

  • Use HTTP GET method
  • Include your API key in the Authorization header as a Bearer token
  • Set Content-Type and Accept headers to application/json
  • The endpoint returns a list of all available banks in the network

Step 3: Understand the Response ​

You should receive a response like this:

json
{
  "success": true,
  "data": [
    {
      "name": "Example Bank Ghana",
      "identifier": "EXB",
      "country_code": "GH"
    },
    {
      "name": "Demo Bank Ghana",
      "identifier": "DEM",
      "country_code": "GH"
    },
    {
      "name": "Sample Bank",
      "identifier": "SAM",
      "country_code": "GH"
    }
  ]
}

Key fields:

  • success: Indicates if the request was successful
  • data: Array of bank objects
  • identifier: Unique bank code used in transaction requests

Step 4: Lookup Customer Banks ​

Now let's find which banks a customer is linked to using their phone number.

bash
curl -X GET \
  https://sandbox-api.fluid-network.com/api/v1/payment-providers/banks/lookup/+233241234567 \
  -H "Authorization: Bearer $FLUID_API_KEY" \
  -H "Content-Type: application/json"

Implementation Notes:

  • Use HTTP GET method
  • Include the phone number in E.164 format (+233...) as a URL parameter
  • URL-encode the phone number if required by your HTTP client
  • The endpoint returns the customer's name and their linked banks

Response:

json
{
  "success": true,
  "phone_number": "+233241234567",
  "customer": "John Doe",
  "data": [
    {
      "name": "Example Bank Ghana",
      "identifier": "EXB",
      "country_code": "GH"
    }
  ]
}

Step 5: Initiate a Debit Request ​

Now let's create a debit request to charge the customer's account.

bash
curl -X POST \
  https://sandbox-api.fluid-network.com/api/v1/payment-providers/debit-requests/charge \
  -H "Authorization: Bearer $FLUID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+233241234567",
    "bank_identifier": "EXB",
    "amount": 100.00,
    "currency": "GHS",
    "narration": "Test Payment",
    "partner_reference": "test_1234567890"
  }'

Implementation Notes:

  • Use HTTP POST method
  • Send request body as JSON with the following required fields:
    • phone_number - Customer's phone in E.164 format
    • bank_identifier - Bank code from the lookup response
    • amount - Transaction amount (number or string)
    • currency - Currency code (e.g., "GHS")
    • narration - Description of the transaction
    • partner_reference - Your unique reference for this transaction
  • Generate a unique partner_reference for each request (e.g., using timestamp)

Response:

json
{
  "success": true,
  "data": {
    "reference": "FLU123456789",
    "status": "pending",
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2025-11-12T14:30:00Z"
  },
  "meta": {
    "timestamp": "2025-11-12T14:30:00Z",
    "request_id": "req_abc123",
    "api_version": "v1"
  }
}

Important: Save the reference value from the response - you'll need it to check the transaction status!

Step 6: Check Transaction Status ​

Finally, let's check the status of our debit request.

bash
# Replace FLU123456789 with your actual reference
curl -X GET \
  https://sandbox-api.fluid-network.com/api/v1/payment-providers/debit-requests/FLU123456789 \
  -H "Authorization: Bearer $FLUID_API_KEY" \
  -H "Content-Type: application/json"

Implementation Notes:

  • Use HTTP GET method
  • Include the transaction reference from Step 5 as a URL parameter
  • Poll this endpoint periodically to check for status changes
  • Consider implementing webhooks for real-time status updates instead of polling

Response:

json
{
  "success": true,
  "data": {
    "reference": "FLU123456789",
    "status": "completed",
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2025-11-12T14:35:00Z"
  },
  "meta": {
    "timestamp": "2025-11-12T14:35:30Z",
    "request_id": "req_xyz789",
    "api_version": "v1"
  }
}

Transaction Statuses ​

StatusDescription
pendingWaiting for customer approval
completedTransaction successful
failedTransaction failed (e.g., insufficient funds)
rejectedCustomer rejected the transaction
timeoutCustomer didn't respond in time

Common Issues ​

401 Unauthorized ​

Problem: Invalid or missing API key

Solution:

bash
# Check your API key is set correctly
echo $FLUID_API_KEY

# Make sure it starts with test_sk_ for Sandbox

422 Unprocessable Entity ​

Problem: Invalid request parameters

Solution: Check that:

  • Phone number is in E.164 format (+233...)
  • Amount is a positive number
  • Bank identifier exists (check Step 2)
  • partner_reference is unique for each request

429 Too Many Requests ​

Problem: Rate limit exceeded

Solution: Implement exponential backoff and respect rate limits (30 requests/minute in Sandbox)

Next Steps ​

Congratulations! You've successfully:

  • ✅ Listed available banks
  • ✅ Looked up a customer's banks
  • ✅ Initiated a debit request
  • ✅ Checked transaction status

What's Next? ​

Need Help? ​

Copyright © 2025 FLUID Network